From e354213395a98fbfe4454e1c386aca7ab6613a66 Mon Sep 17 00:00:00 2001
From: Derick Rethans <derick@php.net>
Date: Mon, 20 May 2013 17:16:05 +0000
Subject: [PATCH] Fixed PHP-789: Document fsync, j, and wtimeout options for
 MongoCollection write operations.

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@330300 c90b9560-bf6c-de11-be94-00142212c4b1
---
 language-snippets.ent                         |  5 ++++-
 .../mongo/mongocollection/batchinsert.xml     | 20 +++++++++++++++----
 reference/mongo/mongocollection/insert.xml    | 16 +++++++++++++--
 reference/mongo/mongocollection/remove.xml    | 15 +++++++++++++-
 reference/mongo/mongocollection/save.xml      | 16 +++++++++++++--
 reference/mongo/mongocollection/update.xml    | 15 +++++++++++++-
 6 files changed, 76 insertions(+), 11 deletions(-)

diff --git a/language-snippets.ent b/language-snippets.ent
index bd98f35afa..ffae0736aa 100644
--- a/language-snippets.ent
+++ b/language-snippets.ent
@@ -1715,9 +1715,12 @@ paths</simpara></warning>
 <!ENTITY mongo.setreadpreference.errors '<para xmlns="http://docbook.org/ns/docbook">Emits <constant>E_WARNING</constant> if either parameter is invalid, or if one or more tag sets are provided with the <constant>MongoClient::RP_PRIMARY</constant> read preference mode.</para>'>
 <!ENTITY mongo.getreadpreference.returnvalues '<para xmlns="http://docbook.org/ns/docbook">This function returns an array describing the read preference. The array contains the values <literal>type</literal> for the string read preference mode (corresponding to the <classname>MongoClient</classname> constants), and <literal>tagsets</literal> containing a list of all tag set criteria. If no tag sets were specified, <literal>tagsets</literal> will not be present in the array.</para>'>
 <!ENTITY mongo.writes.parameters.writeconcern '<listitem xmlns="http://docbook.org/ns/docbook"><para><literal>"w"</literal></para><para>See <link linkend="mongo.writeconcerns">WriteConcerns</link>. The default value for <classname>MongoClient</classname> is <literal>1</literal>.</para></listitem>'>
+<!ENTITY mongo.writes.parameters.writeconcerntimeout '<listitem xmlns="http://docbook.org/ns/docbook"><para><literal>"wtimeout"</literal></para><para>How long to wait for <link linkend="mongo.writeconcerns">WriteConcern</link> acknowledgement. The default value for <classname>MongoClient</classname> is <literal>10000</literal> milliseconds.</para></listitem>'>
 <!ENTITY mongo.writes.parameters.fsync '<listitem xmlns="http://docbook.org/ns/docbook"><para><literal>"fsync"</literal></para><para>Boolean, defaults to &false;. Forces the insert to be synced to disk before returning success. If &true;, an acknowledged insert is implied and will override setting <literal>w</literal> to <literal>0</literal>.</para></listitem>'>
-<!ENTITY mongo.writes.parameters.timeout '<listitem xmlns="http://docbook.org/ns/docbook"><para><literal>"timeout"</literal></para><para>Integer, defaults to <literal>MongoCursor::$timeout</literal>.  If "safe" is set, this sets how long (in milliseconds) for the client to wait for a database response.  If the database does not respond within the timeout period, a <classname>MongoCursorTimeoutException</classname> will be thrown.</para></listitem>'>
+<!-- <!ENTITY mongo.writes.parameters.sockettimeoutms '<listitem xmlns="http://docbook.org/ns/docbook"><para><literal>"socketTimeoutMS"</literal></para><para>Integer, defaults to <literal>MongoCursor::$timeout</literal>.  If acknowledged writes are used, this sets how long (in milliseconds) for the client to wait for a database response.  If the database does not respond within the timeout period, a <classname>MongoCursorTimeoutException</classname> will be thrown.</para></listitem>'> -->
+<!ENTITY mongo.writes.parameters.journal '<listitem xmlns="http://docbook.org/ns/docbook"><para><literal>"j"</literal></para><para>Boolean, defaults to &false;. Forces the insert to be synced to the journal before returning success. If &true;, an acknowledged insert is implied and will override setting <literal>w</literal> to <literal>0</literal>.</para></listitem>'>
 <!ENTITY mongo.writes.parameters.safe '<listitem xmlns="http://docbook.org/ns/docbook"><para><literal>"safe"</literal></para><para><emphasis>Deprecated</emphasis>. Please use the <link linkend="mongo.writeconcerns">WriteConcern</link> <literal>w</literal> option.</para></listitem>'>
+<!ENTITY mongo.writes.parameters.timeout '<listitem xmlns="http://docbook.org/ns/docbook"><para><literal>"timeout"</literal></para><para>Integer, defaults to <literal>MongoCursor::$timeout</literal>.  If acknowledged writes are used, this sets how long (in milliseconds) for the client to wait for a database response.  If the database does not respond within the timeout period, a <classname>MongoCursorTimeoutException</classname> will be thrown.</para></listitem>'>
 <!ENTITY mongo.errors.exceptions.writeconcern '<para xmlns="http://docbook.org/ns/docbook">Throws <classname>MongoCursorException</classname> if the "w" option is set and the write fails.</para><para xmlns="http://docbook.org/ns/docbook">Throws <classname>MongoCursorTimeoutException</classname> if the "w" option is set to a value greater than one and the operation takes longer than <varname>MongoCursor::$timeout</varname> milliseconds to complete.  This does not kill the operation on the server, it is a client-side timeout. The operation in <literal>MongoCollection::$wtimeout</literal> is milliseconds.</para>'>
 <!ENTITY mongo.errors.deprecated '<para xmlns="http://docbook.org/ns/docbook">Issues <constant>E_DEPRECATED</constant> warning</para>'>
 <!ENTITY mongo.gridfs.store.metadata.note '<note xmlns="http://docbook.org/ns/docbook"><para>These fields may also overwrite those that would be created automatically by the driver, as described in the MongoDB core documentation for the <link xlink:href="&url.mongodb.docs.gridfs;#the-files-collection" xmlns:xlink="http://www.w3.org/1999/xlink">files collection</link>. Some practical use cases for this behavior would be to specify a custom <literal>chunkSize</literal> or <literal>_id</literal> for the file.</para></note>'>
diff --git a/reference/mongo/mongocollection/batchinsert.xml b/reference/mongo/mongocollection/batchinsert.xml
index 37ce7d68c8..8e4277d435 100644
--- a/reference/mongo/mongocollection/batchinsert.xml
+++ b/reference/mongo/mongocollection/batchinsert.xml
@@ -47,9 +47,6 @@
       <para>
        Options for the inserts.
        <itemizedlist>
-        &mongo.writes.parameters.writeconcern; 
-        &mongo.writes.parameters.fsync; 
-        &mongo.writes.parameters.timeout; 
         <listitem>
          <para>
           <literal>"continueOnError"</literal>
@@ -75,7 +72,15 @@
           </para>
          </note>
         </listitem>
-        &mongo.writes.parameters.safe; 
+        &mongo.writes.parameters.fsync;
+        &mongo.writes.parameters.journal;
+<!--
+        &mongo.writes.parameters.sockettimeoutms;
+-->
+        &mongo.writes.parameters.writeconcern;
+        &mongo.writes.parameters.writeconcerntimeout;
+        &mongo.writes.parameters.safe;
+        &mongo.writes.parameters.timeout;
        </itemizedlist>
       </para>
      </listitem>
@@ -116,6 +121,13 @@
       </row>
      </thead>
      <tbody>
+<!--
+      <row>
+       <entry>1.5.0</entry>
+       <entry>Renamed the <literal>"timeout"</literal> option to
+       <literal>"socketTimeoutMS"</literal>.</entry>
+      </row>
+-->
       <row>
        <entry>1.2.7</entry>
        <entry>Added <literal>"continueOnError"</literal> option.</entry>
diff --git a/reference/mongo/mongocollection/insert.xml b/reference/mongo/mongocollection/insert.xml
index ef00fba9ea..618efbf11d 100644
--- a/reference/mongo/mongocollection/insert.xml
+++ b/reference/mongo/mongocollection/insert.xml
@@ -52,10 +52,15 @@
       <para>
        Options for the insert.
        <itemizedlist>
-        &mongo.writes.parameters.writeconcern;
         &mongo.writes.parameters.fsync;
-        &mongo.writes.parameters.timeout;
+        &mongo.writes.parameters.journal;
+<!--
+        &mongo.writes.parameters.sockettimeoutms;
+-->
+        &mongo.writes.parameters.writeconcern;
+        &mongo.writes.parameters.writeconcerntimeout;
         &mongo.writes.parameters.safe;
+        &mongo.writes.parameters.timeout;
        </itemizedlist>
       </para>
      </listitem>
@@ -216,6 +221,13 @@
       </row>
      </thead>
      <tbody>
+<!--
+      <row>
+       <entry>1.5.0</entry>
+       <entry>Renamed the <literal>"timeout"</literal> option to
+       <literal>"socketTimeoutMS"</literal>.</entry>
+      </row>
+-->
       <row>
        <entry>1.3.0</entry>
        <entry>
diff --git a/reference/mongo/mongocollection/remove.xml b/reference/mongo/mongocollection/remove.xml
index 1468eff7db..2008af13a7 100644
--- a/reference/mongo/mongocollection/remove.xml
+++ b/reference/mongo/mongocollection/remove.xml
@@ -48,8 +48,14 @@
          </para>
         </listitem>
         &mongo.writes.parameters.fsync;
-        &mongo.writes.parameters.timeout;
+        &mongo.writes.parameters.journal;
+<!--
+        &mongo.writes.parameters.sockettimeoutms;
+-->
+        &mongo.writes.parameters.writeconcern;
+        &mongo.writes.parameters.writeconcerntimeout;
         &mongo.writes.parameters.safe;
+        &mongo.writes.parameters.timeout;
        </itemizedlist>
       </para>
      </listitem>
@@ -87,6 +93,13 @@
       </row>
      </thead>
      <tbody>
+<!--
+      <row>
+       <entry>1.5.0</entry>
+       <entry>Renamed the <literal>"timeout"</literal> option to
+       <literal>"socketTimeoutMS"</literal>.</entry>
+      </row>
+-->
       <row>
        <entry>1.3.0</entry>
        <entry>
diff --git a/reference/mongo/mongocollection/save.xml b/reference/mongo/mongocollection/save.xml
index b865ed2d2e..1d1e5a6909 100644
--- a/reference/mongo/mongocollection/save.xml
+++ b/reference/mongo/mongocollection/save.xml
@@ -51,10 +51,15 @@
       <para>
        Options for the save.
        <itemizedlist>
-        &mongo.writes.parameters.writeconcern;
         &mongo.writes.parameters.fsync;
-        &mongo.writes.parameters.timeout;
+        &mongo.writes.parameters.journal;
+<!--
+        &mongo.writes.parameters.sockettimeoutms;
+-->
+        &mongo.writes.parameters.writeconcern;
+        &mongo.writes.parameters.writeconcerntimeout;
         &mongo.writes.parameters.safe;
+        &mongo.writes.parameters.timeout;
        </itemizedlist>
       </para>
      </listitem>
@@ -94,6 +99,13 @@
       </row>
      </thead>
      <tbody>
+<!--
+      <row>
+       <entry>1.5.0</entry>
+       <entry>Renamed the <literal>"timeout"</literal> option to
+       <literal>"socketTimeoutMS"</literal>.</entry>
+      </row>
+-->
       <row>
        <entry>1.2.0</entry>
        <entry>Added <literal>"timeout"</literal> option.</entry>
diff --git a/reference/mongo/mongocollection/update.xml b/reference/mongo/mongocollection/update.xml
index 702262170b..9bb1ec7cf4 100644
--- a/reference/mongo/mongocollection/update.xml
+++ b/reference/mongo/mongocollection/update.xml
@@ -85,8 +85,14 @@
          </para>
         </listitem>
         &mongo.writes.parameters.fsync;
-        &mongo.writes.parameters.timeout;
+        &mongo.writes.parameters.journal;
+<!--
+        &mongo.writes.parameters.sockettimeoutms;
+-->
+        &mongo.writes.parameters.writeconcern;
+        &mongo.writes.parameters.writeconcerntimeout;
         &mongo.writes.parameters.safe;
+        &mongo.writes.parameters.timeout;
        </itemizedlist>
       </para>
      </listitem>
@@ -124,6 +130,13 @@
       </row>
      </thead>
      <tbody>
+<!--
+      <row>
+       <entry>1.5.0</entry>
+       <entry>Renamed the <literal>"timeout"</literal> option to
+       <literal>"socketTimeoutMS"</literal>.</entry>
+      </row>
+-->
       <row>
        <entry>1.3.0</entry>
        <entry>