From 1eb68ccad461defb2ed0594193653b9e91c003ff Mon Sep 17 00:00:00 2001
From: Kristina Chodorow <kristina@php.net>
Date: Mon, 12 Jul 2010 15:52:05 +0000
Subject: [PATCH] added safe=int opt and fsync

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@301205 c90b9560-bf6c-de11-be94-00142212c4b1
---
 .../mongo/mongocollection/batchinsert.xml     | 34 ++++++++++++++++-
 reference/mongo/mongocollection/insert.xml    | 37 ++++++++++++++++++-
 reference/mongo/mongocollection/remove.xml    | 37 ++++++++++++++++++-
 reference/mongo/mongocollection/update.xml    | 34 ++++++++++++++++-
 4 files changed, 136 insertions(+), 6 deletions(-)

diff --git a/reference/mongo/mongocollection/batchinsert.xml b/reference/mongo/mongocollection/batchinsert.xml
index 4f3338a584..4584fc10e1 100644
--- a/reference/mongo/mongocollection/batchinsert.xml
+++ b/reference/mongo/mongocollection/batchinsert.xml
@@ -43,7 +43,27 @@
           <literal>"safe"</literal>
          </para>
          <para>
-          Check that the inserts succeeded.
+          Can be a boolean or integer, defaults to &false;.  If &false;, the 
+          program continues executing without waiting for a database response. 
+          If &true;, the program will wait for the database response and throw a
+          <classname>MongoCursorException</classname> if the insert did not 
+          succeed.  
+         </para>
+         <para>
+          If <literal>safe</literal> is an integer, will replicate the
+          insert to that many machines before returning success (or throw an
+          exception if the replication times out, see wtimeout).  This overrides
+          the w variable set on the collection.
+         </para>
+        </listitem>
+        <listitem>
+         <para>
+          <literal>"fsync"</literal>
+         </para>
+         <para>
+          Boolean, defaults to &false;.  Forces the insert to be synced to 
+          disk before returning success.  If &true;, a safe insert is implied
+          and will override setting <literal>safe</literal> to &false;.
          </para>
         </listitem>
        </itemizedlist>
@@ -69,6 +89,11 @@
    Throws <classname>MongoCursorException</classname> if the "safe" option is 
    set and the insert fails.
   </para>
+  <para>
+   Throws <classname>MongoCursorTimeoutException</classname> if the "safe" 
+   option is set to a value greater than one and the database cannot replicate 
+   the operation in <literal>MongoCollection::$wtimeout</literal> milliseconds.
+  </para>
  </refsect1>
 
  <refsect1 role="changelog">
@@ -89,6 +114,13 @@
         Added "options" parameter.
        </entry>
       </row>
+      <row>
+       <entry>1.0.9</entry>
+       <entry>
+        Added ability to pass integers to "safe" options (only accepted booleans
+        before) and added "fsync" option.
+       </entry>
+      </row>
      </tbody>
     </tgroup>
    </informaltable>
diff --git a/reference/mongo/mongocollection/insert.xml b/reference/mongo/mongocollection/insert.xml
index b7c9aa20df..6785547a01 100644
--- a/reference/mongo/mongocollection/insert.xml
+++ b/reference/mongo/mongocollection/insert.xml
@@ -48,7 +48,27 @@
           <literal>"safe"</literal>
          </para>
          <para>
-          Check that the insert succeeded.
+          Can be a boolean or integer, defaults to &false;.  If &false;, the 
+          program continues executing without waiting for a database response. 
+          If &true;, the program will wait for the database response and throw a
+          <classname>MongoCursorException</classname> if the insert did not 
+          succeed.  
+         </para>
+         <para>
+          If <literal>safe</literal> is an integer, will replicate the
+          insert to that many machines before returning success (or throw an
+          exception if the replication times out, see wtimeout).  This overrides
+          the w variable set on the collection.
+         </para>
+        </listitem>
+        <listitem>
+         <para>
+          <literal>"fsync"</literal>
+         </para>
+         <para>
+          Boolean, defaults to &false;.  Forces the insert to be synced to 
+          disk before returning success.  If &true;, a safe insert is implied
+          and will override setting <literal>safe</literal> to &false;.
          </para>
         </listitem>
        </itemizedlist>
@@ -71,7 +91,13 @@
  <refsect1 role="errors">
   &reftitle.errors;
   <para>
-   Throws MongoCursorException if the "safe" option is set and the insert fails. (Version 1.0.1+)
+   Throws <classname>MongoCursorException</classname> if the "safe" option is 
+   set and the insert fails. (Version 1.0.1+)
+  </para>
+  <para>
+   Throws <classname>MongoCursorTimeoutException</classname> if the "safe" 
+   option is set to a value greater than one and the database cannot replicate 
+   the operation in <literal>MongoCollection::$wtimeout</literal> milliseconds.
   </para>
  </refsect1>
 
@@ -94,6 +120,13 @@
         second parameter was a boolean indicating the "safe" option.
        </entry>
       </row>
+      <row>
+       <entry>1.0.9</entry>
+       <entry>
+        Added ability to pass integers to "safe" options (only accepted booleans
+        before) and added "fsync" option.
+       </entry>
+      </row>
      </tbody>
     </tgroup>
    </informaltable>
diff --git a/reference/mongo/mongocollection/remove.xml b/reference/mongo/mongocollection/remove.xml
index f077e8a2a3..d96c3c894d 100644
--- a/reference/mongo/mongocollection/remove.xml
+++ b/reference/mongo/mongocollection/remove.xml
@@ -51,7 +51,27 @@
           <literal>"safe"</literal>
          </para>
          <para>
-          Check that the remove succeeded and how many items were removed.
+          Can be a boolean or integer, defaults to &false;.  If &false;, the 
+          program continues executing without waiting for a database response. 
+          If &true;, the program will wait for the database response and throw a
+          <classname>MongoCursorException</classname> if the update did not 
+          succeed.  
+         </para>
+         <para>
+          If <literal>safe</literal> is an integer, will replicate the
+          update to that many machines before returning success (or throw an
+          exception if the replication times out, see wtimeout).  This overrides
+          the w variable set on the collection.
+         </para>
+        </listitem>
+        <listitem>
+         <para>
+          <literal>"fsync"</literal>
+         </para>
+         <para>
+          Boolean, defaults to &false;.  Forces the update to be synced to 
+          disk before returning success.  If &true;, a safe update is implied
+          and will override setting <literal>safe</literal> to &false;.
          </para>
         </listitem>
        </itemizedlist>
@@ -75,7 +95,13 @@
  <refsect1 role="errors">
   &reftitle.errors;
   <para>
-   Throws MongoCursorException if the "safe" option is set and the remove fails.
+   Throws <classname>MongoCursorException</classname> if the "safe" option is 
+   set and the remove fails.
+  </para>
+  <para>
+   Throws <classname>MongoCursorTimeoutException</classname> if the "safe" 
+   option is set to a value greater than one and the database cannot replicate 
+   the operation in <literal>MongoCollection::$wtimeout</literal> milliseconds.
   </para>
  </refsect1>
 
@@ -99,6 +125,13 @@
         there was no safe option.
        </entry>
       </row>
+      <row>
+       <entry>1.0.9</entry>
+       <entry>
+        Added ability to pass integers to "safe" options (only accepted booleans
+        before) and added "fsync" option.
+       </entry>
+      </row>
      </tbody>
     </tgroup>
    </informaltable>
diff --git a/reference/mongo/mongocollection/update.xml b/reference/mongo/mongocollection/update.xml
index 3714f33953..6e5d7f6007 100644
--- a/reference/mongo/mongocollection/update.xml
+++ b/reference/mongo/mongocollection/update.xml
@@ -79,7 +79,27 @@
           <literal>"safe"</literal>
          </para>
          <para>
-          Check that the update succeeded.
+          Can be a boolean or integer, defaults to &false;.  If &false;, the 
+          program continues executing without waiting for a database response. 
+          If &true;, the program will wait for the database response and throw a
+          <classname>MongoCursorException</classname> if the update did not 
+          succeed.  
+         </para>
+         <para>
+          If <literal>safe</literal> is an integer, will replicate the
+          update to that many machines before returning success (or throw an
+          exception if the replication times out, see wtimeout).  This overrides
+          the w variable set on the collection.
+         </para>
+        </listitem>
+        <listitem>
+         <para>
+          <literal>"fsync"</literal>
+         </para>
+         <para>
+          Boolean, defaults to &false;.  Forces the update to be synced to 
+          disk before returning success.  If &true;, a safe update is implied
+          and will override setting <literal>safe</literal> to &false;.
          </para>
         </listitem>
        </itemizedlist>
@@ -103,6 +123,11 @@
    Throws <classname>MongoCursorException</classname> if the "safe" option is 
    set and the update fails.
   </para>
+  <para>
+   Throws <classname>MongoCursorTimeoutException</classname> if the "safe" 
+   option is set to a value greater than one and the database cannot replicate 
+   the operation in <literal>MongoCollection::$wtimeout</literal> milliseconds.
+  </para>
  </refsect1>
 
  <refsect1 role="changelog">
@@ -130,6 +155,13 @@
         Added "safe" option.
        </entry>
       </row>
+      <row>
+       <entry>1.0.9</entry>
+       <entry>
+        Added ability to pass integers to "safe" options (only accepted booleans
+        before) and added "fsync" option.
+       </entry>
+      </row>
      </tbody>
     </tgroup>
    </informaltable>