From 8e5a91bf87a99a2558b24d095b245410b7decf37 Mon Sep 17 00:00:00 2001
From: Derick Rethans <derick@php.net>
Date: Thu, 17 Apr 2014 12:37:40 +0000
Subject: [PATCH] PHP-1043: Document parallelCollectionScan

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@333361 c90b9560-bf6c-de11-be94-00142212c4b1
---
 .../parallelcollectionscan.xml                | 122 ++++++++++++++++++
 reference/mongo/versions.xml                  |   1 +
 2 files changed, 123 insertions(+)
 create mode 100644 reference/mongo/mongocollection/parallelcollectionscan.xml

diff --git a/reference/mongo/mongocollection/parallelcollectionscan.xml b/reference/mongo/mongocollection/parallelcollectionscan.xml
new file mode 100644
index 0000000000..187ec81126
--- /dev/null
+++ b/reference/mongo/mongocollection/parallelcollectionscan.xml
@@ -0,0 +1,122 @@
+<?xml version="1.0" encoding="utf-8"?>
+
+<!-- $Revision: 332247 $ -->
+<refentry xml:id="mongocollection.parallelcollectionscan" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
+ <refnamediv>
+  <refname>MongoCollection::parallelCollectionScan</refname>
+  <refpurpose>Returns an array of cursors to iterator over a full collection in parallel</refpurpose>
+ </refnamediv>
+ <refsect1 role="description">
+  &reftitle.description;
+  <methodsynopsis>
+   <modifier>public</modifier> <type>array[MongoCommandCursor]</type><methodname>MongoCollection::parallelCollectionScan</methodname>
+   <methodparam><type>int</type><parameter>num_cursors</parameter></methodparam>
+  </methodsynopsis>
+  <para>
+   This method returns an array of a maximum of <literal>num_cursors</literal>
+   cursors. An iteration over one of the returned cursors results in a partial
+   set of documents for a collection. Iteration over all the returned cursors
+   results in getting every document back from the collection.
+  </para>
+  <para>
+   This method is a wrapper for the <literal>parallelCollectionScan</literal>
+   MongoDB command.
+  </para>
+ </refsect1>
+
+ <refsect1 role="parameters">
+  &reftitle.parameters;
+  <para>
+   <variablelist>
+    <varlistentry>
+     <term>
+      <parameter>num_cursors</parameter>
+     </term>
+     <listitem>
+      <para>
+       The number of cursors to request from the server. Please note, that the
+       server can return less cursors than you requested.
+      </para>
+     </listitem>
+    </varlistentry>
+   </variablelist>
+  </para>
+ </refsect1>
+
+ <refsect1 role="returnvalues">
+  &reftitle.returnvalues;  
+  <para>
+   Returns an array of <classname>MongoCommandCursor</classname> objects.
+  </para>
+ </refsect1>
+
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <example>
+   <title><function>MongoCollection::parallelCollectionScan</function> example</title>
+   <para>
+    Returning all documents in a collection by using multiple cursors.
+   </para>
+   <programlisting role="php">
+<![CDATA[
+<?php
+$m = new MongoClient;
+$c = $m->demo->cities;
+
+/* Request three cursors */
+$cursors = $c->parallelCollectionScan( 3 );
+
+/* Add all the cursors to the MultipleIterator */
+$mi = new MultipleIterator( MultipleIterator::MIT_NEED_ANY );
+foreach ( $cursors as $cursor )
+{
+    $mi->attachIterator( $cursor );
+}
+
+/* Iterate over all the associated cursors */
+foreach ( $mi as $items )
+{
+    foreach ( $items as $item )
+    {
+        if ( $item !== NULL )
+        {
+            echo $item['name'], "\n";
+        }
+    }
+}
+?>
+]]>
+   </programlisting>
+  </example>
+ </refsect1>
+
+ <refsect1 role="seealso">
+  &reftitle.seealso;
+  <para>
+   <simplelist>
+    <member><classname>MultipleIterator</classname></member>
+    <member><classname>MongoCommandCursor</classname></member>
+    <member><methodname>MongoDb::command</methodname></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/versions.xml b/reference/mongo/versions.xml
index d0951461b0..4cb0dc08d3 100644
--- a/reference/mongo/versions.xml
+++ b/reference/mongo/versions.xml
@@ -97,6 +97,7 @@
  <function name='mongocollection::getwriteconcern' from='PECL mongo &gt;=1.5.0'/>
  <function name='mongocollection::group' from='PECL mongo &gt;=0.9.2'/>
  <function name='mongocollection::insert' from='PECL mongo &gt;=0.9.0'/>
+ <function name='mongocollection::parallelcollectionscan' from='PECL mongo &gt;=1.5.0'/>
  <function name='mongocollection::remove' from='PECL mongo &gt;=0.9.0'/>
  <function name='mongocollection::save' from='PECL mongo &gt;=0.9.0'/>
  <function name='mongocollection::setreadpreference' from='PECL mongo &gt;=1.3.0'/>