svn: /phpdoc/en/trunk/reference/mongo/ mongo/close.xml mongo.xml mongocursor/info.xml mongocursor/slaveokay.xml queries.xml
| From: | Kristina Chodorow | Date: | Wed, 26 Jan 2011 22:22:50 +0000 |
| Subject: | svn: /phpdoc/en/trunk/reference/mongo/ mongo/close.xml mongo.xml mongocursor/info.xml mongocursor/slaveokay.xml queries.xml | ||
| Groups: | php.doc.cvs | ||
| Request: | Send a blank email to doc-cvs+get-7679@lists.php.net to get a copy of this message | ||
kristina Wed, 26 Jan 2011 22:22:50 +0000
Revision: http://svn.php.net/viewvc?view=revision&revision=307768
Log:
improved connection info
Changed paths:
U phpdoc/en/trunk/reference/mongo/mongo/close.xml
U phpdoc/en/trunk/reference/mongo/mongo.xml
U phpdoc/en/trunk/reference/mongo/mongocursor/info.xml
U phpdoc/en/trunk/reference/mongo/mongocursor/slaveokay.xml
U phpdoc/en/trunk/reference/mongo/queries.xml
Modified: phpdoc/en/trunk/reference/mongo/mongo/close.xml
===================================================================
--- phpdoc/en/trunk/reference/mongo/mongo/close.xml 2011-01-26 20:38:28 UTC (rev 307767)
+++ phpdoc/en/trunk/reference/mongo/mongo/close.xml 2011-01-26 22:22:50 UTC (rev 307768)
@@ -4,7 +4,7 @@
<refentry xml:id="mongo.close" xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>Mongo::close</refname>
- <refpurpose>Closes this database connection</refpurpose>
+ <refpurpose>Closes this connection</refpurpose>
</refnamediv>
<refsect1 role="description">
@@ -16,61 +16,19 @@
<para>
This method does not need to be called, except in unusual
circumstances. The driver will cleanly close the database
- connection when the Mongo object goes out of scope.
+ connection when this Mongo instance goes out of scope.
</para>
<para>
- If you are using a service where objects do not go out of scope
- between requests, you may wish to call close() at the end of
- your program to keep old connections from hanging around.
- However, it is probably more efficient to take advantage of
- this fact and simply use a persistent connection, which will
- automatically create a connection if needed and use it for as
- many requests as the application server allows it to exist.
+ If objects do not go out of scope between requests, you may wish to call
+ this method at the end of your program to keep old connections from hanging
+ around. However, it is probably more efficient use a persistent connection,
+ which will automatically create a connection if needed and use it for as
+ many requests as possible.
</para>
<para>
- You may also wish to call close() if you are unsure of the
- state of a connection and wish to guarantee a new connection will
- happen. For example:
+ If you are connected to a replica set, close() will only close the connection
+ to the primary.
</para>
-
- <informalexample>
- <programlisting role="php">
-<![CDATA[
-<?php
-
-$mongo = new Mongo();
-
-/* do stuff where the db connection may be lost */
-
-/* if $mongo is already connected, does nothing */
-$mongo->connect();
-
-?>
-]]>
- </programlisting>
- </informalexample>
-
- <para>
- vs.
- </para>
-
- <informalexample>
- <programlisting role="php">
-<![CDATA[
-<?php
-
-$mongo = new Mongo();
-
-/* do stuff where the db connection may be lost */
-
-/* guarantee a reconnection to the db server */
-$mongo->close();
-$mongo->connect();
-
-?>
-]]>
- </programlisting>
- </informalexample>
</refsect1>
<refsect1 role="parameters">
Modified: phpdoc/en/trunk/reference/mongo/mongo.xml
===================================================================
--- phpdoc/en/trunk/reference/mongo/mongo.xml 2011-01-26 20:38:28 UTC (rev 307767)
+++ phpdoc/en/trunk/reference/mongo/mongo.xml 2011-01-26 22:22:50 UTC (rev 307768)
@@ -11,11 +11,10 @@
<section xml:id="mongo.intro">
&reftitle.intro;
<para>
- The connection point between MongoDB and PHP.
+ A connection between PHP and MongoDB.
</para>
<para>
- This class is used to initiate a connection and for database server commands.
- A typical use is:
+ This class is used to create and manage connections. A typical use is:
<programlisting role="php">
<![CDATA[
<?php
@@ -28,8 +27,9 @@
</programlisting>
</para>
<para>
- See <function>Mongo::__construct</function> for more information about
- creating connections.
+ See <function>Mongo::__construct</function> and the section on
+ <link linkend="mongo.connecting">connecting</link> for more information
+ about creating connections.
</para>
</section>
<!-- }}} -->
Modified: phpdoc/en/trunk/reference/mongo/mongocursor/info.xml
===================================================================
--- phpdoc/en/trunk/reference/mongo/mongocursor/info.xml 2011-01-26 20:38:28 UTC (rev 307767)
+++ phpdoc/en/trunk/reference/mongo/mongocursor/info.xml 2011-01-26 22:22:50 UTC (rev 307768)
@@ -58,7 +58,7 @@
returned by the server in the current batch), and
<literal>server</literal> (which server the query was sent
to—useful in conjunction with
- <function>MongoCursor::slaveOkay</function>.
+ <function>MongoCursor::slaveOkay</function>).
</entry>
</row>
</tbody>
Modified: phpdoc/en/trunk/reference/mongo/mongocursor/slaveokay.xml
===================================================================
--- phpdoc/en/trunk/reference/mongo/mongocursor/slaveokay.xml 2011-01-26 20:38:28 UTC (rev 307767)
+++ phpdoc/en/trunk/reference/mongo/mongocursor/slaveokay.xml 2011-01-26 22:22:50 UTC (rev 307768)
@@ -14,8 +14,44 @@
<methodparam
choice="opt"><type>boolean</type><parameter>okay</parameter><initializer>true</initializer></methodparam>
</methodsynopsis>
<para>
- This method will override the static class variable <varname>slaveOkay</varname>.
+ Calling this will make the driver route reads to slaves if:
+ <itemizedlist>
+ <listitem>
+ <simpara>
+ You are using a replica set and
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ You created a <classname>Mongo</classname> instance using the option
+ <literal>"replicaSet" => true and</literal>
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ There is a healthy slave that can be reached by the driver.
+ </simpara>
+ </listitem>
+ </itemizedlist>
+ You can check which server was used for this query by calling
+ <function>MongoCursor::info</function> after running the query. It's
+ <literal>server</literal> field will show which server the query was sent to.
</para>
+ <para>
+ Note that you should use this function even if you do not use the automatic
+ routing to slaves. If you connect directly to a secondary in a replica set,
+ you still need to call this function, which basically tells the database that
+ you are aware that you might be getting older data and you're okay with that.
+ If you do not call this, you'll get "not master" errors when you try to
+ query.
+ </para>
+ <para>
+ This method will override the static class variable
+ <varname>MongoCursor::slaveOkay</varname>. It will also override
+ <function>Mongo::setSlaveOkay</function>,
+ <function>MongoDB::setSlaveOkay</function> and
+ <function>MongoCollection::setSlaveOkay</function>.
+ </para>
</refsect1>
<refsect1 role="parameters">
Modified: phpdoc/en/trunk/reference/mongo/queries.xml
===================================================================
--- phpdoc/en/trunk/reference/mongo/queries.xml 2011-01-26 20:38:28 UTC (rev 307767)
+++ phpdoc/en/trunk/reference/mongo/queries.xml 2011-01-26 22:22:50 UTC (rev 307768)
@@ -81,7 +81,11 @@
<para>
If we continued to create new <classname>Mongo</classname>s, we should get a
- fairly even distribution between ip1 and ip2.
+ fairly even distribution between ip1 and ip2. Keep in mind that all
+ secondaries listed by the <function>isMaster</function> command will be in
+ the pool of possible readers (even ones with priority 0 or slaveDelay set).
+ If you have certain servers you do not wish to read from, either route reads
+ manually or add the hidden option to the server's replica set configuration.
</para>
<para>