From 84c6f6bcf4abf083badfae16a9fa64acd20bdac0 Mon Sep 17 00:00:00 2001
From: Kristina Chodorow <kristina@php.net>
Date: Thu, 13 May 2010 18:31:22 +0000
Subject: [PATCH] added w & wtimeout doc

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@299357 c90b9560-bf6c-de11-be94-00142212c4b1
---
 reference/mongo/mongocollection.xml    | 46 ++++++++++++++++
 reference/mongo/mongodb.xml            | 73 ++++++++++++++++++++++++++
 reference/mongo/mongogridfs/remove.xml | 13 +----
 3 files changed, 120 insertions(+), 12 deletions(-)

diff --git a/reference/mongo/mongocollection.xml b/reference/mongo/mongocollection.xml
index 04bda48453..e914f642f1 100644
--- a/reference/mongo/mongocollection.xml
+++ b/reference/mongo/mongocollection.xml
@@ -50,6 +50,16 @@
      <varname>db</varname>
      <initializer>&null;</initializer>
     </fieldsynopsis>
+    <fieldsynopsis>
+     <modifier>public</modifier>
+     <type>integer</type>
+     <varname>w</varname>
+    </fieldsynopsis>
+    <fieldsynopsis>
+     <modifier>public</modifier>
+     <type>integer</type>
+     <varname>wtimeout</varname>
+    </fieldsynopsis>
 
     <classsynopsisinfo role="comment">&Methods;</classsynopsisinfo>
     <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.mongocollection')/db:refentry/db:refsect1[@role='description']/descendant::db:methodsynopsis[1])" />
@@ -58,6 +68,42 @@
 
   </section>
 
+  <section>
+   <title>Fields</title>
+   <variablelist>
+    <varlistentry>
+     <term>db</term>
+     <listitem>
+      <para>
+       The "parent" database for this collection.
+      </para>
+     </listitem>
+    </varlistentry>
+    <varlistentry>
+     <term>w</term>
+     <listitem>
+      <para>
+       The number of servers to replicate a change to before returning success.
+       Value is inherited from the parent database. The 
+       <classname>MongoDB</classname> class has a more detailed description of
+       how <literal>w</literal> works.
+      </para>
+     </listitem>
+    </varlistentry>
+    <varlistentry>
+     <term>wtimeout</term>
+     <listitem>
+      <para>
+       The number of milliseconds to wait for <literal>$this->w</literal> 
+       replications to take place.  Value is inherited from the parent database.
+       The <classname>MongoDB</classname> class has a more detailed description 
+       of how <literal>wtimeout</literal> works.
+      </para>
+     </listitem>
+    </varlistentry>
+   </variablelist>
+  </section>
+
   <section>
    &reftitle.seealso;
    <para>
diff --git a/reference/mongo/mongodb.xml b/reference/mongo/mongodb.xml
index f489f376ef..ee0e8f3bc3 100644
--- a/reference/mongo/mongodb.xml
+++ b/reference/mongo/mongodb.xml
@@ -71,6 +71,20 @@ $db = $m->selectDB("example");
      <initializer>2</initializer>
     </fieldsynopsis>
 
+    <classsynopsisinfo role="comment">Fields</classsynopsisinfo>
+    <fieldsynopsis>
+     <modifier>public</modifier>
+     <type>integer</type>
+     <varname>w</varname>
+     <initializer>1</initializer>
+    </fieldsynopsis>
+    <fieldsynopsis>
+     <modifier>public</modifier>
+     <type>integer</type>
+     <varname>wtimeout</varname>
+     <initializer>10000</initializer>
+    </fieldsynopsis>
+
     <classsynopsisinfo role="comment">&Methods;</classsynopsisinfo>
     <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.mongodb')/db:refentry/db:refsect1[@role='description']/descendant::db:methodsynopsis[1])" />
    </classsynopsis>
@@ -115,6 +129,65 @@ $db = $m->selectDB("example");
    </section>
   </section>
 
+  <section>
+   <title>Fields</title>
+   <variablelist>
+    <varlistentry>
+     <term>w</term>
+     <term>1</term>
+     <listitem>
+      <para>
+       The number of servers to replicate a change to before returning success.
+       Inherited by instances of <classname>MongoCollection</classname> derived
+       from this.  <literal>w</literal> functionality is only available in 
+       version 1.5.1+ of the MongoDB server and 1.0.8+ of the driver.
+      </para>
+      <para>
+       <literal>w</literal> is used whenever you perform a "safe" operation
+       (<function>MongoCollection::insert</function>, 
+       <function>MongoCollection::update</function>, 
+       <function>MongoCollection::remove</function>, 
+       <function>MongoCollection::save</function>, and
+       <function>MongoCollection::ensureIndex</function> all support safe 
+       options).  With the default value (1), a safe operation will return once
+       the database server has the operation.  If the server goes down before 
+       the operation has been replicated to a slave, it is possible to lose the
+       operation forever.  Thus, you can specify <literal>w</literal> to be 
+       higher than one and guarantee that at least one slave has the operation
+       before it is considered successful.
+      </para>
+      <para>
+       For example, if <literal>w</literal> is 2, the main server and one slave
+       must have a record of the operation or the driver will throw a 
+       <classname>MongoCursorException</classname>.  It is tempting to set
+       <literal>w</literal> to the total number of slaves + master, but then if 
+       one slave is down the op will fail and an exception will be thrown, so 
+       usually <literal>w=2</literal> is safest (master+1 slave).
+      </para>
+     </listitem>
+    </varlistentry>
+    <varlistentry>
+     <term>wtimeout</term>
+     <term>10000</term>
+     <listitem>
+      <para>
+       The number of milliseconds to wait for <literal>MongoDB::$w</literal> 
+       replications to take place.  Inherited by instances of
+       <classname>MongoCollection</classname> derived from this. 
+       <literal>w</literal> functionality is only available in version 1.5.1+ of
+       the MongoDB server and 1.0.8+ of the driver.
+      </para>
+      <para>
+       Unless <literal>wtimeout</literal> is set, the server waits forever for 
+       replicating to <literal>w</literal> servers to finish.  The driver 
+       defaults to waiting for 10 seconds, you can change this value to alter
+       its behavior.
+      </para>
+     </listitem>
+    </varlistentry>
+   </variablelist>
+  </section>
+
   <section>
    &reftitle.seealso;
    <para>
diff --git a/reference/mongo/mongogridfs/remove.xml b/reference/mongo/mongogridfs/remove.xml
index 851cec320e..843e739499 100644
--- a/reference/mongo/mongogridfs/remove.xml
+++ b/reference/mongo/mongogridfs/remove.xml
@@ -12,7 +12,6 @@
   <methodsynopsis>
    <modifier>public</modifier> <type>boolean</type><methodname>MongoGridFS::remove</methodname>
    <methodparam choice="opt"><type>array</type><parameter>criteria</parameter><initializer>array()</initializer></methodparam>
-   <methodparam choice="opt"><type>boolean</type><parameter>just_one</parameter><initializer>&false;</initializer></methodparam>
   </methodsynopsis>
  </refsect1>
 
@@ -30,16 +29,6 @@
       </para>
      </listitem>
     </varlistentry>   
-    <varlistentry>
-     <term>
-      <parameter>just_one</parameter>
-     </term>
-     <listitem>
-      <para>
-       If only one matching file should be removed.
-      </para>
-     </listitem>
-    </varlistentry>   
    </variablelist>
   </para>
  </refsect1>
@@ -47,7 +36,7 @@
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>
-   Returns if the removal was successful.
+   Returns if the removal was successfully sent to the database.
   </para>
  </refsect1>