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
2025-03-15 16:38:54 +00:00 · 2017-01-19 20:52:14 +00:00 · 2017-01-19 20:52:14 +00:00 · 8a92bfe2ec
commit 8a92bfe2ec
parent 2c8428a75e
5 changed files with 328 additions and 6 deletions
--- a/reference/mongodb/mongodb/driver/readpreference.xml
+++ b/reference/mongodb/mongodb/driver/readpreference.xml
@ -67,7 +67,19 @@
     <varname linkend="mongodb-driver-readpreference.constants.rp-nearest">MongoDB\Driver\ReadPreference::RP_NEAREST</varname>
     <initializer>10</initializer>
    </fieldsynopsis>
-    
+    <fieldsynopsis>
+     <modifier>const</modifier>
+     <type>integer</type>
+     <varname linkend="mongodb-driver-readpreference.constants.no-max-staleness">MongoDB\Driver\ReadPreference::NO_MAX_STALENESS</varname>
+     <initializer>-1</initializer>
+    </fieldsynopsis>
+    <fieldsynopsis>
+     <modifier>const</modifier>
+     <type>integer</type>
+     <varname linkend="mongodb-driver-readpreference.constants.smallest-max-staleness-seconds">MongoDB\Driver\ReadPreference::SMALLEST_MAX_STALENESS_SECONDS</varname>
+     <initializer>90</initializer>
+    </fieldsynopsis>
+
    <classsynopsisinfo role="comment">&Methods;</classsynopsisinfo>
    <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.mongodb-driver-readpreference')/db:refentry/db:refsect1[@role='description']/descendant::db:methodsynopsis[not(@role='procedural')])" />
   </classsynopsis>
@ -129,10 +141,63 @@
     </listitem>
    </varlistentry>

+    <varlistentry xml:id="mongodb-driver-readpreference.constants.no-max-staleness">
+     <term><constant>MongoDB\Driver\ReadPreference::NO_MAX_STALENESS</constant></term>
+     <listitem>
+      <para>
+       The default value for the <literal>"maxStalenessSeconds"</literal>
+       option is to specify no limit on maximum staleness, which means that the
+       driver will not consider a secondary&apos;s lag when choosing where to
+       direct a read operation.
+      </para>
+     </listitem>
+    </varlistentry>
+
+    <varlistentry xml:id="mongodb-driver-readpreference.constants.smallest-max-staleness-seconds">
+     <term><constant>MongoDB\Driver\ReadPreference::SMALLEST_MAX_STALENESS_SECONDS</constant></term>
+     <listitem>
+      <para>
+       The minimum value for the <literal>"maxStalenessSeconds"</literal> option
+       is 90 seconds. The driver estimates secondaries&apos; 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.
+      </para>
+     </listitem>
+    </varlistentry>
+
   </variablelist>
  </section>
 <!-- }}} -->

+  <section role="changelog">
+   &reftitle.changelog;
+   <para>
+    <informaltable>
+     <tgroup cols="2">
+      <thead>
+       <row>
+        <entry>&Version;</entry>
+        <entry>&Description;</entry>
+       </row>
+      </thead>
+      <tbody>
+       <row>
+        <entry>1.2.0</entry>
+        <entry>
+         Added the
+         <constant>MongoDB\Driver\ReadPreference::NO_MAX_STALENESS</constant>
+         and
+         <constant>MongoDB\Driver\ReadPreference::SMALLEST_MAX_STALENESS_SECONDS</constant>
+         constants.
+        </entry>
+       </row>
+      </tbody>
+     </tgroup>
+    </informaltable>
+   </para>
+  </section>

 </partintro>

--- 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" }
 ]]>
   </screen>
-  </example><example>
+  </example>
+  <example>
   <title><function>MongoDB\Driver\ReadPreference::bsonSerialize</function> with secondary read preference and tag sets</title>
   <programlisting role="php">
 <![CDATA[
@ -112,6 +113,38 @@ object(stdClass)#2 (2) {
 }

 { "mode" : "secondary", "tags" : [ { "dc" : "ny" }, { "dc" : "sf", "use" : "reporting" }, {  } ] }
+]]>
+   </screen>
+  </example>
+  <example>
+   <title><function>MongoDB\Driver\ReadPreference::bsonSerialize</function> with secondary read preference and max staleness</title>
+   <programlisting role="php">
+<![CDATA[
+<?php
+
+$rp = new MongoDB\Driver\ReadPreference(
+    MongoDB\Driver\ReadPreference::RP_SECONDARY,
+    null,
+    ['maxStalenessSeconds' => 120]
+);
+var_dump($rp->bsonSerialize());
+
+echo "\n", MongoDB\BSON\toJSON(MongoDB\BSON\fromPHP($rp));
+
+?>
+]]>
+   </programlisting>
+   &example.outputs.similar;
+   <screen>
+<![CDATA[
+object(stdClass)#2 (2) {
+  ["mode"]=>
+  string(9) "secondary"
+  ["maxStalenessSeconds"]=>
+  int(120)
+}
+
+{ "mode" : "secondary", "maxStalenessSeconds" : 120 }
 ]]>
   </screen>
  </example>
--- a/reference/mongodb/mongodb/driver/readpreference/construct.xml
+++ b/reference/mongodb/mongodb/driver/readpreference/construct.xml
@ -12,7 +12,8 @@
  <methodsynopsis>
   <modifier>final</modifier> <modifier>public</modifier> <methodname>MongoDB\Driver\ReadPreference::__construct</methodname>
   <methodparam><type>int</type><parameter>mode</parameter></methodparam>
-   <methodparam choice="opt"><type>array</type><parameter>tagSets</parameter></methodparam>
+   <methodparam choice="opt"><type>array</type><parameter>tagSets</parameter><initializer>&null;</initializer></methodparam>
+   <methodparam choice="opt"><type>array</type><parameter>options</parameter><initializer>[]</initializer></methodparam>
  </methodsynopsis>
  <para>
   Creates a new ReadPreference.
@ -110,6 +111,57 @@
     </para>
    </listitem>
   </varlistentry>
+   <varlistentry>
+    <term><parameter>options</parameter></term>
+    <listitem>
+     <para>
+      <table>
+       <title>options</title>
+       <tgroup cols="3">
+        <thead>
+         <row>
+          <entry>Option</entry>
+          <entry>Type</entry>
+          <entry>Description</entry>
+         </row>
+        </thead>
+        <tbody>
+         <row>
+          <entry>maxStalenessSeconds</entry>
+          <entry><type>integer</type></entry>
+          <entry>
+           <para>
+            Specifies a maximum replication lag, or "staleness", for reads from
+            secondaries. When a secondary&apos;s estimated staleness exceeds
+            this value, the driver stops using it for read operations.
+           </para>
+           <para>
+            If specified, the max staleness must be a signed 32-bit integer
+            greater than or equal to
+            <constant>MongoDB\Driver\ReadPreference::SMALLEST_MAX_STALENESS_SECONDS</constant>.
+           </para>
+           <para>
+            Defaults to
+            <constant>MongoDB\Driver\ReadPreference::NO_MAX_STALENESS</constant>,
+            which means that the driver will not consider a secondary&apos;s lag
+            when choosing where to direct a read operation.
+           </para>
+           <para>
+            This option is not compatible with the
+            <constant>MongoDB\Driver\ReadPreference::RP_PRIMARY</constant> 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.
+           </para>
+          </entry>
+         </row>
+        </tbody>
+       </tgroup>
+      </table>
+     </para>
+    </listitem>
+   </varlistentry>
  </variablelist>
 </refsect1>

@ -117,10 +169,38 @@
  &reftitle.errors;
  <simplelist>
   &mongodb.throws.argumentparsing;
-   <member>Throws <classname>MongoDB\Driver\Exception\InvalidArgumentException</classname> if <parameter>mode</parameter> is invalid or if <parameter>tagSets</parameter> is provided for a primary read preference.</member>
+   <member>Throws <classname>MongoDB\Driver\Exception\InvalidArgumentException</classname> if <parameter>mode</parameter> is invalid.</member>
+   <member>Throws <classname>MongoDB\Driver\Exception\InvalidArgumentException</classname> if <parameter>tagSets</parameter> is provided for a primary read preference or is malformed (i.e. not an array of zero or more documents).</member>
+   <member>Throws <classname>MongoDB\Driver\Exception\InvalidArgumentException</classname> if the <literal>"maxStalenessSeconds"</literal> option is provided for a primary read preference or is out of range.</member>
  </simplelist>
 </refsect1>

+ <refsect1 role="changelog">
+  &reftitle.changelog;
+  <para>
+   <informaltable>
+    <tgroup cols="2">
+     <thead>
+      <row>
+       <entry>&Version;</entry>
+       <entry>&Description;</entry>
+      </row>
+     </thead>
+     <tbody>
+      <row>
+       <entry>1.2.0</entry>
+       <entry>
+        <para>
+         Added a third <parameter>options</parameter> argument, which supports
+         the <literal>"maxStalenessSeconds"</literal> option.
+        </para>
+       </entry>
+      </row>
+     </tbody>
+    </tgroup>
+   </informaltable>
+  </para>
+ </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
@ -131,14 +211,44 @@
 <?php

 /* Prefer a secondary node but fall back to a primary. */
-$rp = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::RP_SECONDARY_PREFERRED);
+var_dump(new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::RP_SECONDARY_PREFERRED));

 /* Prefer a node in the New York data center with lowest latency. */
-$rp = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::RP_NEAREST, [['dc' => '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]));

 ?>
 ]]>
   </programlisting>
+   &example.outputs;
+   <screen>
+<![CDATA[
+object(MongoDB\Driver\ReadPreference)#1 (1) {
+  ["mode"]=>
+  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)
+}
+]]>
+   </screen>
  </example>
 </refsect1>

--- a/reference/mongodb/mongodb/driver/readpreference/getmaxstalenessseconds.xml
+++ b/reference/mongodb/mongodb/driver/readpreference/getmaxstalenessseconds.xml
@ -0,0 +1,113 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- $Revision: 336263 $ -->
+
+<refentry xml:id="mongodb-driver-readpreference.getmaxstalenessseconds" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
+ <refnamediv>
+  <refname>MongoDB\Driver\ReadPreference::getMaxStalenessSeconds</refname>
+  <refpurpose>Returns the ReadPreference&apos;s "maxStalenessSeconds" option</refpurpose>
+ </refnamediv>
+
+ <refsect1 role="description">
+  &reftitle.description;
+  <methodsynopsis>
+   <modifier>final</modifier> <modifier>public</modifier> <type>integer</type><methodname>MongoDB\Driver\ReadPreference::getMaxStalenessSeconds</methodname>
+   <void />
+  </methodsynopsis>
+  <para>
+  </para>
+ </refsect1>
+
+ <refsect1 role="parameters">
+  &reftitle.parameters;
+  &no.function.parameters;
+ </refsect1>
+
+ <refsect1 role="returnvalues">
+  &reftitle.returnvalues;
+  <para>
+   Returns the ReadPreference&apos;s "maxStalenessSeconds" option. If no max
+   staleness has been specified,
+   <constant>MongoDB\Driver\ReadPreference::NO_MAX_STALENESS</constant> will be
+   returned.
+  </para>
+ </refsect1>
+
+ <refsect1 role="errors">
+  &reftitle.errors;
+  <simplelist>
+   &mongodb.throws.argumentparsing;
+  </simplelist>
+ </refsect1>
+
+
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <example>
+   <title><function>MongoDB\Driver\ReadPreference::getMaxStalenessSeconds</function> example</title>
+   <programlisting role="php">
+<![CDATA[
+<?php
+
+$rp = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::RP_SECONDARY);
+var_dump($rp->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());
+
+?>
+]]>
+   </programlisting>
+   &example.outputs;
+   <screen>
+<![CDATA[
+int(-1)
+int(-1)
+int(90)
+int(1000)
+]]>
+   </screen>
+  </example>
+ </refsect1>
+
+
+ <refsect1 role="seealso">
+  &reftitle.seealso;
+  <simplelist>
+   <member><link xlink:href="&url.mongodb.docs.readpreference;">Read Preference reference</link></member>
+  </simplelist>
+ </refsect1>
+
+</refentry>
+
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-omittag:t
+sgml-shorttag:t
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:1
+sgml-indent-data:t
+indent-tabs-mode:nil
+sgml-parent-document:nil
+sgml-default-dtd-file:"~/.phpdoc/manual.ced"
+sgml-exposed-tags:nil
+sgml-local-catalogs:nil
+sgml-local-ecat-files:nil
+End:
+vim600: syn=xml fen fdm=syntax fdl=2 si
+vim: et tw=78 syn=sgml
+vi: ts=1 sw=1
+-->
--- a/reference/mongodb/versions.xml
+++ b/reference/mongodb/versions.xml
@ -46,6 +46,7 @@
 <function name='mongodb\driver\readpreference' from='mongodb &gt;=1.0.0'/>
 <function name='mongodb\driver\readpreference::__construct' from='mongodb &gt;=1.0.0'/>
 <function name='mongodb\driver\readpreference::bsonserialize' from='mongodb &gt;=1.2.0'/>
+ <function name='mongodb\driver\readpreference::getmaxstalenessseconds' from='mongodb &gt;=1.2.0'/>
 <function name='mongodb\driver\readpreference::getmode' from='mongodb &gt;=1.0.0'/>
 <function name='mongodb\driver\readpreference::gettagsets' from='mongodb &gt;=1.0.0'/>