From afcb5ee093e6779d659d36d353f0112d15a55cb3 Mon Sep 17 00:00:00 2001
From: Kristina Chodorow <kristina@php.net>
Date: Thu, 7 Jan 2010 21:59:21 +0000
Subject: [PATCH] added timeout, updated constructor

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@293232 c90b9560-bf6c-de11-be94-00142212c4b1
---
 reference/mongo/mongo.xml               | 64 +---------------
 reference/mongo/mongo/construct.xml     | 13 ++++
 reference/mongo/mongocursor/timeout.xml | 97 +++++++++++++++++++++++++
 reference/mongo/versions.xml            |  2 +
 4 files changed, 113 insertions(+), 63 deletions(-)
 create mode 100644 reference/mongo/mongocursor/timeout.xml

diff --git a/reference/mongo/mongo.xml b/reference/mongo/mongo.xml
index 1c6a57ed6f..6ac91bb2cc 100644
--- a/reference/mongo/mongo.xml
+++ b/reference/mongo/mongo.xml
@@ -21,53 +21,7 @@
 <?php
 
 $m = new Mongo(); // connect
-$db = $m->selectDB("foo"); // get a database object
-
-?>
-]]>
-    </programlisting>
-   </para>
-
-   <para>
-    This class has two static fields: <varname>Mongo::$connections</varname> and
-    <varname>Mongo::$pconnections</varname> which track the number of open
-    connections and persistent connections, respectively.
-    <varname>Mongo::$connections</varname> is inclusive, it basically counts all
-    open sockets, including persistent connections. 
-   </para>
-   <para>
-    An example of how different types of connections affect these variables:
-    <programlisting>
-<![CDATA[
-<?php
-
-/* 
- * start:
- * Mongo::$connections is 0
- * Mongo::$pconnections is 0
- */
-
-$m1 = new Mongo(); 
-
-/* 
- * Mongo::$connections is 1
- * Mongo::$pconnections is 0
- */
-
-$m2 = new Mongo("localhost", array("persist" => "foo"));
-
-/* 
- * Mongo::$connections is 2
- * Mongo::$pconnections is 1
- */
-
-// reuse persistent connection
-$m3 = new Mongo("localhost", array("persist" => "foo"));
-
-/* 
- * Mongo::$connections is 2
- * Mongo::$pconnections is 1
- */
+$db = $m->foo; // get the database named "foo"
 
 ?>
 ]]>
@@ -114,22 +68,6 @@ $m3 = new Mongo("localhost", array("persist" => "foo"));
      <initializer>27017</initializer>
     </fieldsynopsis>
 
-    <classsynopsisinfo role="comment">Static Fields</classsynopsisinfo>
-    <fieldsynopsis>
-     <modifier>public</modifier>
-     <modifier>static</modifier>
-     <type>int</type>
-     <varname>connections</varname>
-     <initializer>0</initializer>
-    </fieldsynopsis>
-    <fieldsynopsis>
-     <modifier>public</modifier>
-     <modifier>static</modifier>
-     <type>int</type>
-     <varname>pconnections</varname>
-     <initializer>0</initializer>
-    </fieldsynopsis>
-
     <classsynopsisinfo role="comment">Fields</classsynopsisinfo>
     <fieldsynopsis>
      <modifier>public</modifier>
diff --git a/reference/mongo/mongo/construct.xml b/reference/mongo/mongo/construct.xml
index ff51ac273b..f3c104c8d3 100644
--- a/reference/mongo/mongo/construct.xml
+++ b/reference/mongo/mongo/construct.xml
@@ -34,6 +34,19 @@
    it could not connect to any of the hosts, it will throw a 
    <classname>MongoConnectionException</classname>.
   </para>
+
+  <warning>
+
+   <title><parameter>server</parameter> Format</title>
+
+   <para>
+    Before version 1.0.2, <parameter>server</parameter> could not be prefixed
+    with <literal>mongodb://</literal>, contain username and password, or 
+    contain more than two hostnames.  See the changelog below for more details.
+   </para>
+
+  </warning>
+
   <para>
    If you elect not to connect immediately (you pass the option 
    <literal>array("connect" => false)</literal>), you will need to call 
diff --git a/reference/mongo/mongocursor/timeout.xml b/reference/mongo/mongocursor/timeout.xml
new file mode 100644
index 0000000000..a4a3c01511
--- /dev/null
+++ b/reference/mongo/mongocursor/timeout.xml
@@ -0,0 +1,97 @@
+<?xml version="1.0" encoding="utf-8"?>
+
+<!-- $Revision$ -->
+<refentry xml:id="mongocursor.timeout" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
+ <refnamediv>
+  <refname>MongoCursor::timeout</refname>
+  <refpurpose>Sets a client-side timeout for this query</refpurpose>
+ </refnamediv>
+
+ <refsect1 role="description">
+  &reftitle.description;
+  <methodsynopsis>
+   <modifier>public</modifier> <type>MongoCursor</type><methodname>MongoCursor::timeout</methodname>
+   <methodparam><type>int</type><parameter>ms</parameter></methodparam>
+  </methodsynopsis>
+ </refsect1>
+
+ <refsect1 role="parameters">
+  &reftitle.parameters;
+  <variablelist>
+   <varlistentry>
+    <term>
+     <parameter>ms</parameter>
+    </term>
+    <listitem>
+     <para>
+      The number of milliseconds for the cursor to wait for a response.  By 
+      default, the cursor will wait forever.
+     </para>
+    </listitem>
+   </varlistentry>   
+  </variablelist>
+ </refsect1>
+
+ <refsect1 role="returnvalues">
+  &reftitle.returnvalues;  
+  <para>
+   This cursor.
+  </para>
+ </refsect1>
+
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <example>
+   <title><function>MongoCursor::timeout</function> example</title>
+   <para>
+    A query where the cursor waits for one second for a response.
+   </para>
+   <programlisting role="php">
+<![CDATA[
+<?php
+
+$cursor = $collection->find()->timeout(1000);
+
+try {
+  foreach ($cursor as $value) {
+    print_r($value);
+  }
+}
+catch(MongoCursorTimeoutException $e) {
+  echo "query took too long!";
+}
+
+?>
+]]>
+   </programlisting>
+  </example>
+ </refsect1>
+
+ <refsect1 role="errors">
+  &reftitle.errors;
+  <para>
+   Causes methods that fetch results to throw 
+   <classname>MongoCursorTimeoutException</classname>s if the query takes longer
+   than the number of milliseconds specified.
+  </para>
+ </refsect1>
+</refentry>
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-omittag:t
+sgml-shorttag:t
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:1
+sgml-indent-data:t
+sgml-parent-document:nil
+sgml-default-dtd-file:"~/.phpdoc/manual.ced"
+sgml-exposed-tags:nil
+sgml-local-catalogs:nil
+sgml-local-ecat-files:nil
+End:
+vim600: syn=xml fen fdm=syntax fdl=2 si
+vim: et tw=78 syn=sgml
+vi: ts=1 sw=1
+--> 
diff --git a/reference/mongo/versions.xml b/reference/mongo/versions.xml
index 5402bfcae8..bbc2a9d47e 100644
--- a/reference/mongo/versions.xml
+++ b/reference/mongo/versions.xml
@@ -70,6 +70,7 @@
  <function name='mongocursor::next' from='PECL mongo &gt;=0.9.0'/>
  <function name='mongocursor::skip' from='PECL mongo &gt;=0.9.0'/>
  <function name='mongocursor::sort' from='PECL mongo &gt;=0.9.0'/>
+ <function name='mongocursor::timeout' from='PECL mongo &gt;=1.0.3'/>
  <function name='mongocursor::current' from='PECL mongo &gt;=0.9.0'/>
  <function name='mongocursor::reset' from='PECL mongo &gt;=0.9.0'/>
  <function name='mongocursor::rewind' from='PECL mongo &gt;=0.9.0'/>
@@ -105,6 +106,7 @@
 
  <!-- MongoId -->
  <function name='mongoid::__construct' from='PECL mongo &gt;= 0.8.0'/>
+ <function name='mongoid::getTimestamp' from='PECL mongo &gt;= 1.0.1'/>
  <function name='mongoid::__tostring' from='PECL mongo &gt;= 0.8.0'/>
  <!-- MongoRegex -->
  <function name='mongoregex::__construct' from='PECL mongo &gt;= 0.8.1'/>