From 34575dba02e14db5c1a9e874b3fccfc5fbfab87b Mon Sep 17 00:00:00 2001
From: Derick Rethans <derick@php.net>
Date: Wed, 30 Oct 2013 11:05:02 +0000
Subject: [PATCH] PHP-938: please update description of 'fsync' write concern
 flag.

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@332016 c90b9560-bf6c-de11-be94-00142212c4b1
---
 language-snippets.ent                     |  2 +-
 reference/mongo/mongoclient/construct.xml | 18 +++++++++++++-----
 2 files changed, 14 insertions(+), 6 deletions(-)

diff --git a/language-snippets.ent b/language-snippets.ent
index 652d48b191..61e6b3da7c 100644
--- a/language-snippets.ent
+++ b/language-snippets.ent
@@ -1729,7 +1729,7 @@ paths</simpara></warning>
 <!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.fsync '<listitem xmlns="http://docbook.org/ns/docbook"><para><literal>"fsync"</literal></para><para>Boolean, defaults to &false;. If journalling is enabled, it works exactly like <literal>"j"</literal>. If journalling is not enabled, it 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><note><para>This option is <emphasis>deprecated</emphasis>. Please use the <literal>"j"</literal> option instead.</para></note></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>'>
diff --git a/reference/mongo/mongoclient/construct.xml b/reference/mongo/mongoclient/construct.xml
index 989f00d82b..ddf7c7497e 100644
--- a/reference/mongo/mongoclient/construct.xml
+++ b/reference/mongo/mongoclient/construct.xml
@@ -131,13 +131,21 @@ mongodb://[username:password@]host1[:port1][,host2[:port2:],...]/db
          </para>
          <para>
           When <literal>fsync</literal> is set, all write operations on the
-          database will block until the database server has flushed its
-          database files to disk. This makes write operations a lot slower,
+          database will only return when the write has been synched to disk.
+          This makes write operations a lot slower,
           but it guarantees that the write operation has succeeded and
-          committed to disk. Please avoid <emphasis>using</emphasis> this
-          option and use the <literal>journal</literal> option instead,
-          perhaps in combination with the <literal>w</literal> option.
+          committed to disk. If you have journalling enabled in MongoDB (the
+          default) then the sync happens only to the
+          <emphasis>journal</emphasis>. If journalling is not enabled, then
+          using <literal>fsync</literal> requires a full flush to disk.
          </para>
+         <warning>
+          <para>
+           Please <emphasis>do not use</emphasis> this option as it is
+           deprecated, but use <literal>journal</literal> option instead,
+           perhaps in combination with the <literal>w</literal> option.
+          </para>
+         </warning>
         </listitem>
         <listitem>
          <para>