From 8a92bfe2ecc2f609e38679631a72a0cbcbacacb8 Mon Sep 17 00:00:00 2001 From: Jeremy Mikola Date: Thu, 19 Jan 2017 20:52:14 +0000 Subject: [PATCH] Document MongoDB\Driver\ReadPreference maxStalenessSeconds option https://jira.mongodb.org/browse/PHPC-827 git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@341730 c90b9560-bf6c-de11-be94-00142212c4b1 --- .../mongodb/mongodb/driver/readpreference.xml | 67 +++++++++- .../driver/readpreference/bsonserialize.xml | 35 +++++- .../driver/readpreference/construct.xml | 118 +++++++++++++++++- .../readpreference/getmaxstalenessseconds.xml | 113 +++++++++++++++++ reference/mongodb/versions.xml | 1 + 5 files changed, 328 insertions(+), 6 deletions(-) create mode 100644 reference/mongodb/mongodb/driver/readpreference/getmaxstalenessseconds.xml diff --git a/reference/mongodb/mongodb/driver/readpreference.xml b/reference/mongodb/mongodb/driver/readpreference.xml index 9017a9b3de..c7d3e689a0 100644 --- a/reference/mongodb/mongodb/driver/readpreference.xml +++ b/reference/mongodb/mongodb/driver/readpreference.xml @@ -67,7 +67,19 @@ MongoDB\Driver\ReadPreference::RP_NEAREST 10 - + + const + integer + MongoDB\Driver\ReadPreference::NO_MAX_STALENESS + -1 + + + const + integer + MongoDB\Driver\ReadPreference::SMALLEST_MAX_STALENESS_SECONDS + 90 + + &Methods; @@ -129,10 +141,63 @@ + + MongoDB\Driver\ReadPreference::NO_MAX_STALENESS + + + The default value for the "maxStalenessSeconds" + option is to specify no limit on maximum staleness, which means that the + driver will not consider a secondary's lag when choosing where to + direct a read operation. + + + + + + MongoDB\Driver\ReadPreference::SMALLEST_MAX_STALENESS_SECONDS + + + The minimum value for the "maxStalenessSeconds" option + is 90 seconds. The driver estimates secondaries' staleness by + periodically checking the latest write date of each replica set member. + Since these checks are infrequent, the staleness estimate is coarse. + Thus, the driver cannot enforce a max staleness value of less than 90 + seconds. + + + + +
+ &reftitle.changelog; + + + + + + &Version; + &Description; + + + + + 1.2.0 + + Added the + MongoDB\Driver\ReadPreference::NO_MAX_STALENESS + and + MongoDB\Driver\ReadPreference::SMALLEST_MAX_STALENESS_SECONDS + constants. + + + + + + +
diff --git a/reference/mongodb/mongodb/driver/readpreference/bsonserialize.xml b/reference/mongodb/mongodb/driver/readpreference/bsonserialize.xml index f9b8f31f10..66a7704da2 100644 --- a/reference/mongodb/mongodb/driver/readpreference/bsonserialize.xml +++ b/reference/mongodb/mongodb/driver/readpreference/bsonserialize.xml @@ -64,7 +64,8 @@ object(stdClass)#2 (1) { { "mode" : "primary" } ]]> - + + <function>MongoDB\Driver\ReadPreference::bsonSerialize</function> with secondary read preference and tag sets + + + + <function>MongoDB\Driver\ReadPreference::bsonSerialize</function> with secondary read preference and max staleness + + 120] +); +var_dump($rp->bsonSerialize()); + +echo "\n", MongoDB\BSON\toJSON(MongoDB\BSON\fromPHP($rp)); + +?> +]]> + + &example.outputs.similar; + + + string(9) "secondary" + ["maxStalenessSeconds"]=> + int(120) +} + +{ "mode" : "secondary", "maxStalenessSeconds" : 120 } ]]> diff --git a/reference/mongodb/mongodb/driver/readpreference/construct.xml b/reference/mongodb/mongodb/driver/readpreference/construct.xml index 53fc135911..dc787386c3 100644 --- a/reference/mongodb/mongodb/driver/readpreference/construct.xml +++ b/reference/mongodb/mongodb/driver/readpreference/construct.xml @@ -12,7 +12,8 @@ final public MongoDB\Driver\ReadPreference::__construct intmode - arraytagSets + arraytagSets&null; + arrayoptions[] Creates a new ReadPreference. @@ -110,6 +111,57 @@ + + options + + + + options + + + + Option + Type + Description + + + + + maxStalenessSeconds + integer + + + Specifies a maximum replication lag, or "staleness", for reads from + secondaries. When a secondary's estimated staleness exceeds + this value, the driver stops using it for read operations. + + + If specified, the max staleness must be a signed 32-bit integer + greater than or equal to + MongoDB\Driver\ReadPreference::SMALLEST_MAX_STALENESS_SECONDS. + + + Defaults to + MongoDB\Driver\ReadPreference::NO_MAX_STALENESS, + which means that the driver will not consider a secondary's lag + when choosing where to direct a read operation. + + + This option is not compatible with the + MongoDB\Driver\ReadPreference::RP_PRIMARY mode. + Specifying a max staleness also requires all MongoDB instances in + the deployment to be using MongoDB 3.4+. An exception will be thrown + at execution time if any MongoDB instances in the deployment are of + an older server version. + + + + + +
+ + + @@ -117,10 +169,38 @@ &reftitle.errors; &mongodb.throws.argumentparsing; - Throws MongoDB\Driver\Exception\InvalidArgumentException if mode is invalid or if tagSets is provided for a primary read preference. + Throws MongoDB\Driver\Exception\InvalidArgumentException if mode is invalid. + Throws MongoDB\Driver\Exception\InvalidArgumentException if tagSets is provided for a primary read preference or is malformed (i.e. not an array of zero or more documents). + Throws MongoDB\Driver\Exception\InvalidArgumentException if the "maxStalenessSeconds" option is provided for a primary read preference or is out of range. + + &reftitle.changelog; + + + + + + &Version; + &Description; + + + + + 1.2.0 + + + Added a third options argument, which supports + the "maxStalenessSeconds" option. + + + + + + + + &reftitle.examples; @@ -131,14 +211,44 @@ 'ny']]); +var_dump(new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::RP_NEAREST, [['dc' => 'ny']])); + +/* Require a secondary node whose replication lag is within two minutes of the primary */ +var_dump(new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::RP_SECONDARY, null, ['maxStalenessSeconds' => 120])); ?> ]]> + &example.outputs; + + + string(18) "secondaryPreferred" +} +object(MongoDB\Driver\ReadPreference)#1 (2) { + ["mode"]=> + string(7) "nearest" + ["tags"]=> + array(1) { + [0]=> + object(stdClass)#2 (1) { + ["dc"]=> + string(2) "ny" + } + } +} +object(MongoDB\Driver\ReadPreference)#1 (2) { + ["mode"]=> + string(9) "secondary" + ["maxStalenessSeconds"]=> + int(120) +} +]]> + diff --git a/reference/mongodb/mongodb/driver/readpreference/getmaxstalenessseconds.xml b/reference/mongodb/mongodb/driver/readpreference/getmaxstalenessseconds.xml new file mode 100644 index 0000000000..c265fe1151 --- /dev/null +++ b/reference/mongodb/mongodb/driver/readpreference/getmaxstalenessseconds.xml @@ -0,0 +1,113 @@ + + + + + + MongoDB\Driver\ReadPreference::getMaxStalenessSeconds + Returns the ReadPreference's "maxStalenessSeconds" option + + + + &reftitle.description; + + final public integerMongoDB\Driver\ReadPreference::getMaxStalenessSeconds + + + + + + + + &reftitle.parameters; + &no.function.parameters; + + + + &reftitle.returnvalues; + + Returns the ReadPreference's "maxStalenessSeconds" option. If no max + staleness has been specified, + MongoDB\Driver\ReadPreference::NO_MAX_STALENESS will be + returned. + + + + + &reftitle.errors; + + &mongodb.throws.argumentparsing; + + + + + + &reftitle.examples; + + <function>MongoDB\Driver\ReadPreference::getMaxStalenessSeconds</function> example + +getMaxStalenessSeconds()); + +$rp = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::RP_SECONDARY, null, [ + 'maxStalenessSeconds' => MongoDB\Driver\ReadPreference::NO_MAX_STALENESS, +]); +var_dump($rp->getMaxStalenessSeconds()); + +$rp = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::RP_SECONDARY, null, [ + 'maxStalenessSeconds' => MongoDB\Driver\ReadPreference::SMALLEST_MAX_STALENESS_SECONDS, +]); +var_dump($rp->getMaxStalenessSeconds()); + +$rp = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::RP_SECONDARY, null, [ + 'maxStalenessSeconds' => 1000, +]); +var_dump($rp->getMaxStalenessSeconds()); + +?> +]]> + + &example.outputs; + + + + + + + + + &reftitle.seealso; + + Read Preference reference + + + + + + diff --git a/reference/mongodb/versions.xml b/reference/mongodb/versions.xml index 49d1ac80d2..722a68127a 100644 --- a/reference/mongodb/versions.xml +++ b/reference/mongodb/versions.xml @@ -46,6 +46,7 @@ +