Merge pull request #415 from mongodb/phplib-268

PHPLIB-268 Add option maxAwaitTimeMS on getMore commands

Author: kvwalker

docs/includes/apiargs-MongoDBCollection-method-find-option.yaml

@@ -93,6 +93,10 @@ interface: phpmethod
 operation: ~
 optional: true
 ---
+source:
+  file: apiargs-common-option.yaml
+  ref: maxAwaitTimeMS
+---
 source:
   file: apiargs-common-option.yaml
   ref: maxTimeMS

docs/includes/apiargs-common-option.yaml

@@ -10,6 +10,17 @@ operation: ~
 optional: true
 ---
 arg_name: option
+name: maxAwaitTimeMS
+type: integer
+description: |
+    Positive integer denoting the time limit in milliseconds for the server to block
+    a getMore operation if no data is available. This option should only be used if
+    cursorType is TAILABLE_AWAIT.
+interface: phpmethod
+operation: ~
+optional: true
+---
+arg_name: option
 name: readConcern
 type: :php:`MongoDB\\Driver\\ReadConcern <class.mongodb-driver-readconcern>`
 description: |

src/Operation/Find.php

@@ -78,6 +78,9 @@ class Find implements Executable
      *
      *  * max (document): The exclusive upper bound for a specific index.
      *
+     *  * maxAwaitTimeMS (integer): The maxium amount of time for the server to wait
+     *    on new documents to satisfy a query, if cursorType is TAILABLE_AWAIT.
+     *
      *  * maxScan (integer): Maximum number of documents or index keys to scan
      *    when executing the query.
      *
@@ -179,6 +182,10 @@ public function __construct($databaseName, $collectionName, $filter, array $opti
             throw InvalidArgumentException::invalidType('"max" option', $options['max'], 'array or object');
         }
 
+        if (isset($options['maxAwaitTimeMS']) && ! is_integer($options['maxAwaitTimeMS'])) {
+            throw InvalidArgumentException::invalidType('"maxAwaitTimeMS" option', $options['maxAwaitTimeMS'], 'integer');
+        }
+
         if (isset($options['maxScan']) && ! is_integer($options['maxScan'])) {
             throw InvalidArgumentException::invalidType('"maxScan" option', $options['maxScan'], 'integer');
         }
@@ -298,7 +305,7 @@ private function createQuery()
             }
         }
 
-        foreach (['allowPartialResults', 'batchSize', 'comment', 'hint', 'limit', 'maxScan', 'maxTimeMS', 'noCursorTimeout', 'oplogReplay', 'projection', 'readConcern', 'returnKey', 'showRecordId', 'skip', 'snapshot', 'sort'] as $option) {
+        foreach (['allowPartialResults', 'batchSize', 'comment', 'hint', 'limit', 'maxAwaitTimeMS', 'maxScan', 'maxTimeMS', 'noCursorTimeout', 'oplogReplay', 'projection', 'readConcern', 'returnKey', 'showRecordId', 'skip', 'snapshot', 'sort'] as $option) {
             if (isset($this->options[$option])) {
                 $options[$option] = $this->options[$option];
             }

tests/Operation/FindFunctionalTest.php

@@ -3,7 +3,9 @@
 namespace MongoDB\Tests\Operation;
 
 use MongoDB\Driver\BulkWrite;
+use MongoDB\Operation\CreateCollection;
 use MongoDB\Operation\CreateIndexes;
+use MongoDB\Operation\DropCollection;
 use MongoDB\Operation\Find;
 use MongoDB\Tests\CommandObserver;
 use stdClass;
@@ -123,6 +125,39 @@ public function provideTypeMapOptionsAndExpectedDocuments()
         ];
     }
 
+    public function testMaxAwaitTimeMS()
+    {
+        $maxAwaitTimeMS = 10;
+
+        // Create a capped collection.
+        $databaseName = $this->getDatabaseName();
+        $cappedCollectionName = $this->getCollectionName();
+        $cappedCollectionOptions = [
+            'capped' => true,
+            'max' => 100,
+            'size' => 1048576,
+        ];
+
+        $operation = new CreateCollection($databaseName, $cappedCollectionName, $cappedCollectionOptions);
+        $operation->execute($this->getPrimaryServer());
+
+        // Insert documents into the capped collection.
+        $bulkWrite = new BulkWrite(['ordered' => true]);
+        $bulkWrite->insert(['_id' => 1]);
+        $result = $this->manager->executeBulkWrite($this->getNamespace(), $bulkWrite);
+
+        $operation = new Find($databaseName, $cappedCollectionName, [], ['cursorType' => Find::TAILABLE_AWAIT, 'maxAwaitTimeMS' => $maxAwaitTimeMS]);
+        $cursor = $operation->execute($this->getPrimaryServer());
+        $it = new \IteratorIterator($cursor);
+
+        // Make sure we await results for no more than the maxAwaitTimeMS.
+        $it->rewind();
+        $it->next();
+        $startTime = microtime(true);
+        $it->next();
+        $this->assertGreaterThanOrEqual($maxAwaitTimeMS * 0.001, microtime(true) - $startTime);
+    }
+
     /**
      * Create data fixtures.
      *

tests/Operation/FindTest.php

@@ -60,6 +60,10 @@ public function provideInvalidConstructorOptions()
             $options[][] = ['max' => $value];
         }
 
+        foreach ($this->getInvalidIntegerVAlues() as $value) {
+            $options[][] = ['maxAwaitTimeMS' => $value];
+        }
+
         foreach ($this->getInvalidIntegerValues() as $value) {
             $options[][] = ['maxScan' => $value];
         }