svn: /phpdoc/en/trunk/ language-snippets.ent reference/mongo/mongoclient/construct.xml
| From: | Jeremy Mikola | Date: | Mon, 04 Aug 2014 22:06:20 +0000 |
| Subject: | svn: /phpdoc/en/trunk/ language-snippets.ent reference/mongo/mongoclient/construct.xml | ||
| Groups: | php.doc.cvs | ||
| Request: | Send a blank email to doc-cvs+get-12702@lists.php.net to get a copy of this message | ||
jmikola Mon, 04 Aug 2014 22:06:20 +0000
Revision: http://svn.php.net/viewvc?view=revision&revision=334483
Log:
Revise MongoDB connect/socket timeout docs
Document that default values for MongoClient options and implications of negative timeouts.
https://jira.mongodb.org/browse/PHP-791
Changed paths:
U phpdoc/en/trunk/language-snippets.ent
U phpdoc/en/trunk/reference/mongo/mongoclient/construct.xml
Modified: phpdoc/en/trunk/language-snippets.ent
===================================================================
--- phpdoc/en/trunk/language-snippets.ent 2014-08-04 21:17:50 UTC (rev 334482)
+++ phpdoc/en/trunk/language-snippets.ent 2014-08-04 22:06:20 UTC (rev 334483)
@@ -1749,7 +1749,7 @@
<!ENTITY mongo.writes.parameters.writeconcerntimeout '<listitem xmlns="http://docbook.org/ns/docbook"><para><literal>"wtimeout"</literal></para><para>Deprecated
alias for
<literal>"wTimeoutMS"</literal>.</para></listitem>'>
<!ENTITY mongo.writes.parameters.writeconcerntimeoutms '<listitem xmlns="http://docbook.org/ns/docbook"><para><literal>"wTimeoutMS"</literal></para><para>This
option specifies the time limit, in milliseconds, for <link
linkend="mongo.writeconcerns">write concern</link> acknowledgement. It is only
applicable when <literal>"w"</literal> is greater than
<literal>1</literal>, as the timeout pertains to replication. If the write concern is
not satisfied within the time limit, a <classname>MongoCursorException</classname> will
be thrown. A value of <literal>0</literal> may be specified to block indefinitely. The
default value for <classname>MongoClient</classname> is
<literal>10000</literal> (ten seconds).</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 journaling is enabled, it works exactly like
<literal>"j"</literal>. If journaling is not enabled, the write operation
blocks until it is synced to database files on disk. If &true;, an acknowledged insert is
implied and this option will override setting <literal>"w"</literal> to
<literal>0</literal>.</para><note><simpara>If journaling is enabled,
users are strongly encouraged to use the <literal>"j"</literal> option instead
of <literal>"fsync"</literal>. Do not use
<literal>"fsync"</literal> and <literal>"j"</literal>
simultaneously, as that will result in an
error.</simpara></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.sockettimeoutms '<listitem xmlns="http://docbook.org/ns/docbook"><para><literal>"socketTimeoutMS"</literal></para><para>This
option specifies the time limit, in milliseconds, for socket communication. If the server does not
respond within the timeout period, a <classname>MongoCursorTimeoutException</classname>
will be thrown and there will be no way to determine if the server actually handled the write or
not. A value of <literal>-1</literal> may be specified to block indefinitely. The
default value for <classname>MongoClient</classname> is
<literal>30000</literal> (30 seconds).</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 write operation to block until it is synced to the journal on
disk. If &true;, an acknowledged write is implied and this option will override setting
<literal>"w"</literal> to
<literal>0</literal>.</para><note><simpara>If this option is used and
journaling is disabled, MongoDB 2.6+ will raise an error and the write will fail; older server
versions will simply ignore the option.</simpara></note></listitem>'>
<!ENTITY mongo.writes.parameters.safe '<listitem xmlns="http://docbook.org/ns/docbook"><para><literal>"safe"</literal></para><para>Deprecated.
Please use the <link linkend="mongo.writeconcerns">write concern</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>Deprecated
alias for
<literal>"socketTimeoutMS"</literal>.</para></listitem>'>
Modified: phpdoc/en/trunk/reference/mongo/mongoclient/construct.xml
===================================================================
--- phpdoc/en/trunk/reference/mongo/mongoclient/construct.xml 2014-08-04 21:17:50 UTC (rev 334482)
+++ phpdoc/en/trunk/reference/mongo/mongoclient/construct.xml 2014-08-04 22:06:20 UTC (rev 334483)
@@ -162,8 +162,13 @@
</para>
<para>
How long a connection can take to be opened before timing out in
- milliseconds.
+ milliseconds. Defaults to <literal>60000</literal> (60 seconds).
</para>
+ <para>
+ If <literal>-1</literal> is specified, no connection timeout will be
+ applied and PHP will use
+ <link
linkend="ini.default-socket-timeout">default_socket_timeout</link>.
+ </para>
</listitem>
<listitem>
<para>
@@ -298,16 +303,23 @@
<literal>"socketTimeoutMS"</literal>
</para>
<para>
- How long a send or receive on a socket can take before timing out.
- <note>
- <simpara>
- This is a client side timeout. If an <literal>insert</literal> hits
- the <literal>"socketTimeoutMS"</literal> value there is no way to
- know if the server actually received the write or not.
- </simpara>
- </note>
- Defaults to 30seconds. This value can also be set on each cursor using
<methodname>MongoCursor::timeout</methodname>.
+ How long a socket operation (read or write) can take before timing out
+ in milliseconds. Defaults to <literal>30000</literal> (30 seconds).
</para>
+ <para>
+ If <literal>-1</literal> is specified, socket operations may block
+ indefinitely. This option may also be set on a per-operation basis
+ using <methodname>MongoCursor::timeout</methodname> for queries or the
+ <literal>"socketTimeoutMS"</literal> option for write methods.
+ </para>
+ <note>
+ <simpara>
+ This is a client-side timeout. If a write operation times out, there
+ is no way to know if the server actually handled the write or not, as
+ a <classname>MongoCursorTimeoutException</classname> will be thrown
+ in lieu of returning a write result.
+ </simpara>
+ </note>
</listitem>
<listitem>
<para>