From 986408d67a8552e15e505edb6c7b4ff15251692e Mon Sep 17 00:00:00 2001
From: Kristina Chodorow <kristina@php.net>
Date: Thu, 18 Aug 2011 19:37:11 +0000
Subject: [PATCH] added MongoPool functions

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@315150 c90b9560-bf6c-de11-be94-00142212c4b1
---
 reference/mongo/misc.xml              |   1 +
 reference/mongo/mongo/getpoolsize.xml |  18 +++-
 reference/mongo/mongo/pooldebug.xml   |   7 ++
 reference/mongo/mongo/setpoolsize.xml |  33 ++++---
 reference/mongo/mongopool.xml         |  75 ++++++++++++++
 reference/mongo/mongopool/getsize.xml |  96 ++++++++++++++++++
 reference/mongo/mongopool/info.xml    | 137 ++++++++++++++++++++++++++
 reference/mongo/mongopool/setsize.xml | 122 +++++++++++++++++++++++
 8 files changed, 471 insertions(+), 18 deletions(-)
 create mode 100644 reference/mongo/mongopool.xml
 create mode 100644 reference/mongo/mongopool/getsize.xml
 create mode 100644 reference/mongo/mongopool/info.xml
 create mode 100644 reference/mongo/mongopool/setsize.xml

diff --git a/reference/mongo/misc.xml b/reference/mongo/misc.xml
index b7f3a432eb..30f3c83ad2 100644
--- a/reference/mongo/misc.xml
+++ b/reference/mongo/misc.xml
@@ -6,5 +6,6 @@
  <title>Miscellaneous</title>
 
  &reference.mongo.mongolog;
+ &reference.mongo.mongopool;
 
 </part>
diff --git a/reference/mongo/mongo/getpoolsize.xml b/reference/mongo/mongo/getpoolsize.xml
index 5c23ce046a..c0005e2e13 100644
--- a/reference/mongo/mongo/getpoolsize.xml
+++ b/reference/mongo/mongo/getpoolsize.xml
@@ -6,20 +6,28 @@
   <refname>Mongo::getPoolSize</refname>
   <refpurpose>Get pool size for connection pools</refpurpose>
  </refnamediv>
- 
+
  <refsect1 role="description">
   &reftitle.description;
   <methodsynopsis>
    <modifier>public</modifier> <modifier>static</modifier> <type>int</type><methodname>Mongo::getPoolSize</methodname>
    <void/>
   </methodsynopsis>
+
+  <warning xmlns="http://docbook.org/ns/docbook">
+   <simpara>This feature has been <emphasis>DEPRECATED</emphasis> as of version
+    1.2.3. Relying on this feature is highly discouraged.  Please use
+    <function>MongoPool::getSize</function> instead.
+   </simpara>
+  </warning>
+
  </refsect1>
- 
+
  <refsect1 role="parameters">
   &reftitle.parameters;
   &no.function.parameters;
  </refsect1>
- 
+
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>
@@ -62,7 +70,7 @@ var_dump(Mongo::poolDebug());
    </programlisting>
   </example>
  </refsect1>
- 
+
  <refsect1 role="seealso"><!-- {{{ -->
   &reftitle.seealso;
   <para>
@@ -73,7 +81,7 @@ var_dump(Mongo::poolDebug());
    </simplelist>
   </para>
  </refsect1><!-- }}} -->
- 
+
 </refentry>
 <!-- Keep this comment at the end of the file
 Local variables:
diff --git a/reference/mongo/mongo/pooldebug.xml b/reference/mongo/mongo/pooldebug.xml
index 1bf6cb7303..fd8b540079 100644
--- a/reference/mongo/mongo/pooldebug.xml
+++ b/reference/mongo/mongo/pooldebug.xml
@@ -14,6 +14,13 @@
    <void/>
   </methodsynopsis>
 
+  <warning xmlns="http://docbook.org/ns/docbook">
+   <simpara>This feature has been <emphasis>DEPRECATED</emphasis> as of version
+    1.2.3. Relying on this feature is highly discouraged.  Please use
+    <function>MongoPool::info</function> instead.
+   </simpara>
+  </warning>
+
   <para>
    Returns an array of information about all connection pools.
   </para>
diff --git a/reference/mongo/mongo/setpoolsize.xml b/reference/mongo/mongo/setpoolsize.xml
index 26274638e3..a885d22aa9 100644
--- a/reference/mongo/mongo/setpoolsize.xml
+++ b/reference/mongo/mongo/setpoolsize.xml
@@ -6,19 +6,26 @@
   <refname>Mongo::setPoolSize</refname>
   <refpurpose>Set the size for future connection pools.</refpurpose>
  </refnamediv>
- 
+
  <refsect1 role="description">
   &reftitle.description;
   <methodsynopsis>
    <modifier>public</modifier> <modifier>static</modifier> <type>bool</type><methodname>Mongo::setPoolSize</methodname>
    <methodparam><type>int</type><parameter>size</parameter></methodparam>
   </methodsynopsis>
-  
+
+  <warning xmlns="http://docbook.org/ns/docbook">
+   <simpara>This feature has been <emphasis>DEPRECATED</emphasis> as of version
+    1.2.3. Relying on this feature is highly discouraged.  Please use
+    <function>MongoPool::setSize</function> instead.
+   </simpara>
+  </warning>
+
   <para>
    Sets the max number of connections new pools will be able to create.
   </para>
  </refsect1>
- 
+
  <refsect1 role="parameters">
   &reftitle.parameters;
   <para>
@@ -38,24 +45,24 @@
    </variablelist>
   </para>
  </refsect1>
- 
+
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>
    Returns the former value of pool size.
   </para>
  </refsect1>
- 
- 
+
+
  <refsect1 role="examples"><!-- {{{ -->
   &reftitle.examples;
   <para>
    <example xml:id="mongo.setpoolsize.example.basic"><!-- {{{ -->
     <title><function>Mongo::setPoolSize</function> example</title>
     <para>
-     If you set the pool size to <literal>n</literal> and then create 
-     <literal>n</literal> connections, attempting to create an 
-     <literal>n+1</literal>st connection will throw a 
+     If you set the pool size to <literal>n</literal> and then create
+     <literal>n</literal> connections, attempting to create an
+     <literal>n+1</literal>st connection will throw a
      <classname>MongoConnectionException</classname>.
     </para>
     <programlisting role="php">
@@ -87,9 +94,9 @@ Stack trace:
     </screen>
    </example><!-- }}} -->
   </para>
- </refsect1><!-- }}} --> 
- 
- 
+ </refsect1><!-- }}} -->
+
+
  <refsect1 role="seealso"><!-- {{{ -->
   &reftitle.seealso;
   <para>
@@ -99,7 +106,7 @@ Stack trace:
     <member>The <link linkend="mongo.connecting">connection</link> documentation.</member>
    </simplelist>
   </para>
- </refsect1><!-- }}} --> 
+ </refsect1><!-- }}} -->
 </refentry>
 <!-- Keep this comment at the end of the file
 Local variables:
diff --git a/reference/mongo/mongopool.xml b/reference/mongo/mongopool.xml
new file mode 100644
index 0000000000..58503214c7
--- /dev/null
+++ b/reference/mongo/mongopool.xml
@@ -0,0 +1,75 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- $Revision$ -->
+
+<phpdoc:classref xml:id="class.mongopool" xmlns:phpdoc="http://php.net/ns/phpdoc" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude">
+
+ <title>The MongoPool class</title>
+ <titleabbrev>MongoPool</titleabbrev>
+
+ <partintro>
+
+<!-- {{{ MongoPool intro -->
+  <section xml:id="mongopool.intro">
+   &reftitle.intro;
+   <para>
+    In version 1.2.0 of the driver, built-in connection pooling was introduced.
+    This class gives you some control and information about pooling.
+   </para>
+   <note>
+    <para>
+     The functions in this class were originally static members of
+     <classname>Mongo</classname>.  It is highly recommended that you use these
+     functions in the future, as the static <classname>Mongo</classname>
+     functions are considered deprecated.
+    </para>
+   </note>
+  </section>
+<!-- }}} -->
+
+  <section xml:id="mongopool.synopsis">
+   &reftitle.classsynopsis;
+
+<!-- {{{ Synopsis -->
+   <classsynopsis>
+    <ooclass><classname>MongoPool</classname></ooclass>
+
+<!-- {{{ Class synopsis -->
+    <classsynopsisinfo>
+     <ooclass>
+      <classname>MongoPool</classname>
+     </ooclass>
+    </classsynopsisinfo>
+<!-- }}} -->
+
+    <classsynopsisinfo role="comment">&Methods;</classsynopsisinfo>
+    <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.mongodate')/db:refentry/db:refsect1[@role='description']/descendant::db:methodsynopsis[1])" />
+   </classsynopsis>
+<!-- }}} -->
+
+  </section>
+ </partintro>
+
+ &reference.mongo.entities.mongopool;
+
+</phpdoc:classref>
+
+<!-- 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
+indent-tabs-mode:nil
+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/mongopool/getsize.xml b/reference/mongo/mongopool/getsize.xml
new file mode 100644
index 0000000000..74f8923fb3
--- /dev/null
+++ b/reference/mongo/mongopool/getsize.xml
@@ -0,0 +1,96 @@
+<?xml version="1.0" encoding="utf-8"?>
+
+<!-- $Revision$ -->
+<refentry xml:id="mongopool.getsize" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
+ <refnamediv>
+  <refname>MongoPool::getSize</refname>
+  <refpurpose>Get pool size for connection pools</refpurpose>
+ </refnamediv>
+
+ <refsect1 role="description">
+  &reftitle.description;
+  <methodsynopsis>
+   <modifier>public</modifier> <modifier>static</modifier> <type>int</type><methodname>MongoPool::getSize</methodname>
+   <void/>
+  </methodsynopsis>
+ </refsect1>
+
+ <refsect1 role="parameters">
+  &reftitle.parameters;
+  &no.function.parameters;
+ </refsect1>
+
+ <refsect1 role="returnvalues">
+  &reftitle.returnvalues;
+  <para>
+   Returns the current pool size.
+  </para>
+ </refsect1>
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <example>
+   <title>Changing pool size</title>
+   <para>
+    This returns the default pool size, sets a new pool size, then prints the
+    new pool size and the pool debugging information.  Note that changing the
+    pool size only affects new connection pools, it does not change old ones.
+   </para>
+   <programlisting role="php">
+<![CDATA[
+<?php
+
+$connection = new Mongo("host1");
+
+// pool size is -1
+echo "pool size is: ".MongoPool::getSize()."\n";
+
+echo "setting pool size to 200\n";
+
+MongoPool::setSize(200);
+
+// pool size is 200
+echo "pool size is: ".MongoPool::getSize()."\n";
+
+$conn2 = new Mongo("host2");
+
+// remaining for host1 is -2
+// remaining for host2 is 199
+var_dump(Mongo::poolDebug());
+
+?>
+]]>
+   </programlisting>
+  </example>
+ </refsect1>
+
+ <refsect1 role="seealso"><!-- {{{ -->
+  &reftitle.seealso;
+  <para>
+   <simplelist>
+    <member><function>MongoPool::setSize</function></member>
+    <member><function>MongoPool::info</function></member>
+    <member>The <link linkend="mongo.connecting">connection</link> documentation.</member>
+   </simplelist>
+  </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/mongopool/info.xml b/reference/mongo/mongopool/info.xml
new file mode 100644
index 0000000000..679e830ca1
--- /dev/null
+++ b/reference/mongo/mongopool/info.xml
@@ -0,0 +1,137 @@
+<?xml version="1.0" encoding="utf-8"?>
+
+<!-- $Revision$ -->
+<refentry xml:id="mongopool.info" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
+ <refnamediv>
+  <refname>MongoPool::info</refname>
+  <refpurpose>Returns information about all connection pools.</refpurpose>
+ </refnamediv>
+
+ <refsect1 role="description">
+  &reftitle.description;
+  <methodsynopsis>
+   <modifier>public</modifier> <type>array</type><methodname>MongoPool::info</methodname>
+   <void/>
+  </methodsynopsis>
+
+  <para>
+   Returns an array of information about all connection pools.
+  </para>
+ </refsect1>
+
+ <refsect1 role="parameters">
+  &reftitle.parameters;
+  &no.function.parameters;
+ </refsect1>
+
+ <refsect1 role="returnvalues">
+  &reftitle.returnvalues;
+  <para>
+   Each connection pool has an identifier, which starts with the host. For each
+   pool, this function shows the following fields:
+   <variablelist>
+    <varlistentry>
+     <term>
+      <parameter>in use</parameter>
+     </term>
+     <listitem>
+      <para>
+       The number of connections currently being used by
+       <classname>Mongo</classname> instances.
+      </para>
+     </listitem>
+    </varlistentry>
+    <varlistentry>
+     <term>
+      <parameter>in pool</parameter>
+     </term>
+     <listitem>
+      <para>
+       The number of connections currently in the pool (not being used).
+      </para>
+     </listitem>
+    </varlistentry>
+    <varlistentry>
+     <term>
+      <parameter>remaining</parameter>
+     </term>
+     <listitem>
+      <para>
+       The number of connections that could be created by this pool. For
+       example, suppose a pool had 5 connections remaining and 3 connections in
+       the pool.  We could create 8 new instances of
+       <classname>Mongo</classname> before we exhausted this pool (assuming no
+       instances of <classname>Mongo</classname> went out of scope, returning
+       their connections to the pool).
+      </para>
+      <para>
+       A negative number means that this pool will spawn unlimited connections.
+      </para>
+      <para>
+       Before a pool is created, you can change the max number of connections by
+       calling <function>Mongo::setPoolSize</function>. Once a pool is showing
+       up in the output of this function, its size cannot be changed.
+      </para>
+     </listitem>
+    </varlistentry>
+    <varlistentry>
+     <term>
+      <parameter>total</parameter>
+     </term>
+     <listitem>
+      <para>
+       The total number of connections allowed for this pool.  This should be
+       greater than or equal to "in use" + "in pool" (or -1).
+      </para>
+     </listitem>
+    </varlistentry>
+    <varlistentry>
+     <term>
+      <parameter>timeout</parameter>
+     </term>
+     <listitem>
+      <para>
+       The socket timeout for connections in this pool. This is how long
+       connections in this pool will attempt to connect to a server before
+       giving up.
+      </para>
+     </listitem>
+    </varlistentry>
+    <varlistentry>
+     <term>
+      <parameter>waiting</parameter>
+     </term>
+     <listitem>
+      <para>
+       If you have capped the pool size, workers requesting connections from
+       the pool may block until other workers return their connections. This
+       field shows how many milliseconds workers have blocked for connections to
+       be released.  If this number keeps increasing, you may want to use
+       <function>MongoPool::setSize</function> to add more connections to your
+       pool.
+      </para>
+     </listitem>
+    </varlistentry>
+   </variablelist>
+  </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/mongopool/setsize.xml b/reference/mongo/mongopool/setsize.xml
new file mode 100644
index 0000000000..b4e12ef775
--- /dev/null
+++ b/reference/mongo/mongopool/setsize.xml
@@ -0,0 +1,122 @@
+<?xml version="1.0" encoding="utf-8"?>
+
+<!-- $Revision$ -->
+<refentry xml:id="mongopool.setsize" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
+ <refnamediv>
+  <refname>MongoPool::setSize</refname>
+  <refpurpose>Set the size for future connection pools.</refpurpose>
+ </refnamediv>
+
+ <refsect1 role="description">
+  &reftitle.description;
+  <methodsynopsis>
+   <modifier>public</modifier> <modifier>static</modifier> <type>bool</type><methodname>MongoPool::setSize</methodname>
+   <methodparam><type>int</type><parameter>size</parameter></methodparam>
+  </methodsynopsis>
+
+  <para>
+   Sets the max number of connections new pools will be able to create.
+  </para>
+ </refsect1>
+
+ <refsect1 role="parameters">
+  &reftitle.parameters;
+  <para>
+   <variablelist>
+    <varlistentry>
+     <term>
+      <parameter>size</parameter>
+     </term>
+     <listitem>
+      <para>
+       The max number of connections future pools will be able to create.
+       Negative numbers mean that the pool will spawn an infinite number of
+       connections.
+      </para>
+     </listitem>
+    </varlistentry>
+   </variablelist>
+  </para>
+ </refsect1>
+
+ <refsect1 role="returnvalues">
+  &reftitle.returnvalues;
+  <para>
+   Returns the former value of pool size.
+  </para>
+ </refsect1>
+
+
+ <refsect1 role="examples"><!-- {{{ -->
+  &reftitle.examples;
+  <para>
+   <example xml:id="mongopool.setpoolsize.example.basic"><!-- {{{ -->
+    <title><function>Mongo::setPoolSize</function> example</title>
+    <para>
+     If you set the pool size to <literal>n</literal> and then create
+     <literal>n</literal> connections, attempting to create an
+     <literal>n+1</literal>st connection will throw a
+     <classname>MongoConnectionException</classname>.
+    </para>
+    <programlisting role="php">
+<![CDATA[
+<?php
+
+// only allow one connection to a server
+MongoPool::setSize(1);
+
+// creates one connection to localhost:27017
+$m1 = new Mongo();
+
+// attempt to create a second connection to localhost:27017
+// only one connection is allowed, so this will throw an exception
+$m2 = new Mongo();
+
+?>
+]]>
+    </programlisting>
+    &example.outputs.similar;
+    <screen>
+<![CDATA[
+Fatal error: Uncaught exception 'MongoConnectionException' with message 'no more connections in pool' in /path/to/php/script.php:10
+Stack trace:
+#0 /path/to/php/script.php(10): Mongo->__construct()
+#1 {main}
+  thrown in /path/to/php/script.php on line 10
+]]>
+    </screen>
+   </example><!-- }}} -->
+  </para>
+ </refsect1><!-- }}} -->
+
+
+ <refsect1 role="seealso"><!-- {{{ -->
+  &reftitle.seealso;
+  <para>
+   <simplelist>
+    <member><function>MongoPool::getSize</function></member>
+    <member><function>MongoPool::info</function></member>
+    <member>The <link linkend="mongo.connecting">connection</link> documentation.</member>
+   </simplelist>
+  </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
+-->