DOCSP-22185 BACKPORT (#1112)

Author: Dave

source/includes/fact-multiple-cursor-monitors.rst

@@ -0,0 +1,28 @@
+MongoDB provides multiple ways to iterate on a cursor. 
+
+The :method:`cursor.hasNext()` method blocks and waits for the next
+event. To monitor the ``watchCursor`` cursor and iterate over the
+events, use ``hasNext()`` like this:
+
+.. code-block:: javascript
+
+   while (!watchCursor.isClosed()) {
+      if (watchCursor.hasNext()) {
+        firstChange = watchCursor.next();
+        break;
+      }
+   }
+
+The :method:`cursor.tryNext()` method is non-blocking. To monitor
+the ``watchCursor`` cursor and iterate over the events, use
+``tryNext()`` like this:
+
+.. code-block:: javascript
+
+   while (!watchCursor.isClosed()) {
+     let next = watchCursor.tryNext()
+     while (next !== null) {
+       printjson(next);
+       next = watchCursor.tryNext()
+     }
+   }

source/reference/method/Mongo.watch.txt

@@ -259,6 +259,11 @@ have a :ref:`role <roles>` that grants the following :ref:`privilege
 The built-in :authrole:`read` role provides the appropriate
 privileges.
 
+Cursor Iteration
+----------------
+
+.. include:: /includes/fact-multiple-cursor-monitors.rst
+
 Example
 -------
 
@@ -272,16 +277,18 @@ except for the ``admin``, ``local``, and the ``config`` databases.
    watchCursor = db.getMongo().watch()
 
 Iterate the cursor to check for new events. Use the
-:method:`cursor.isExhausted()` method to ensure the loop only exits
-if the change stream cursor is closed *and* there are no objects
-remaining in the latest batch:
+:method:`cursor.isClosed()` method with the :method:`cursor.tryNext()`
+method to ensure the loop only exits if the change stream cursor is
+closed *and* there are no objects remaining in the latest batch:
 
 .. code-block:: javascript
 
-   while (!watchCursor.isExhausted()){
-      if (watchCursor.hasNext()){
-         printjson(watchCursor.next());
-      }
+   while (!watchCursor.isClosed()) {
+     let next = watchCursor.tryNext()
+     while (next !== null) {
+       printjson(next);
+       next = watchCursor.tryNext()
+     }
    }
 
 For complete documentation on change stream output, see

source/reference/method/cursor.tryNext.txt

@@ -0,0 +1,29 @@
+=============
+cursor.next()
+=============
+
+.. default-domain:: mongodb
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+.. method:: cursor.tryNext()
+
+
+   .. include:: /includes/fact-mongosh-shell-method.rst
+
+
+   :returns: The next document in the cursor returned by the
+             :method:`db.collection.find()` method or ``null``.
+             
+
+Behavior
+--------
+
+``cursor.tryNext()`` is a special case of the :method:`cursor.next()`
+method that returns the next element in the iteration if available or
+else ``null``.
+

source/reference/method/db.collection.watch.txt

@@ -245,6 +245,11 @@ have a :ref:`role <roles>` that grants the following :ref:`privilege
 The built-in :authrole:`read` role provides the appropriate
 privileges.
 
+Cursor Iteration
+----------------
+
+.. include:: /includes/fact-multiple-cursor-monitors.rst
+
 Examples
 --------
 
@@ -259,16 +264,18 @@ The following operation opens a change stream cursor against the
    watchCursor = db.getSiblingDB("data").sensors.watch()
 
 Iterate the cursor to check for new events. Use the
-:method:`cursor.isExhausted()` method to ensure the loop only exits
-if the change stream cursor is closed *and* there are no objects
-remaining in the latest batch:
+:method:`cursor.isClosed()` method with the :method:`cursor.tryNext()`
+method to ensure the loop only exits if the change stream cursor is
+closed *and* there are no objects remaining in the latest batch:
 
 .. code-block:: javascript
 
-   while (!watchCursor.isExhausted()){
-      if (watchCursor.hasNext()){
-         printjson(watchCursor.next());
-      }
+   while (!watchCursor.isClosed()) {
+     let next = watchCursor.tryNext()
+     while (next !== null) {
+       printjson(next);
+       next = watchCursor.tryNext()
+     }
    }
 
 For complete documentation on change stream output, see
@@ -293,16 +300,18 @@ the ``data.sensors`` collection using the
    )
 
 Iterate the cursor to check for new events. Use the
-:method:`cursor.isExhausted()` method to ensure the loop only exits
-if the change stream cursor is closed *and* there are no objects
-remaining in the latest batch:
+:method:`cursor.isClosed()` method with the :method:`cursor.tryNext()`
+method to ensure the loop only exits if the change stream cursor is
+closed *and* there are no objects remaining in the latest batch:
 
 .. code-block:: javascript
 
-   while (!watchCursor.isExhausted()){
-      if (watchCursor.hasNext()){
-         printjson(watchCursor.next());
-      }
+   while (!watchCursor.isClosed()) {
+     let next = watchCursor.tryNext()
+     while (next !== null) {
+       printjson(next);
+       next = watchCursor.tryNext()
+     }
    }
 
 For any update operation, the change event returns the result of the
@@ -334,13 +343,13 @@ filter only ``insert`` events:
    )
 
 Iterate the cursor to check for new events. Use the
-:method:`cursor.isExhausted()` method to ensure the loop only exits
-if the change stream cursor is closed *and* there are no objects
-remaining in the latest batch:
+:method:`cursor.isClosed()` method with the :method:`cursor.hasNext()`
+method to ensure the loop only exits if the change stream cursor is
+closed *and* there are no objects remaining in the latest batch:
 
 .. code-block:: javascript
 
-   while (!watchCursor.isExhausted()){
+   while (!watchCursor.isClosed()){
       if (watchCursor.hasNext()){
          printjson(watchCursor.next());
       }
@@ -369,7 +378,7 @@ rolled off the cluster's oplog.
    let watchCursor = db.getSiblingDB("data").sensors.watch();
    let firstChange;
 
-   while (!watchCursor.isExhausted()) {
+   while (!watchCursor.isClosed()) {
       if (watchCursor.hasNext()) {
         firstChange = watchCursor.next();
         break;
@@ -386,13 +395,14 @@ rolled off the cluster's oplog.
    )
 
 Iterate the cursor to check for new events. Use the
-:method:`cursor.isExhausted()` method to ensure the loop only exits
-if the change stream cursor is closed *and* there are no objects
-remaining in the latest batch:
+:method:`cursor.isClosed()` method with the :method:`cursor.hasNext()`
+method to ensure the loop only exits if the change stream cursor is
+closed *and* there are no objects remaining in the latest batch:
+
 
 .. code-block:: javascript
 
-   while (!resumedWatchCursor.isExhausted()){
+   while (!resumedWatchCursor.isClosed()){
       if (resumedWatchCursor.hasNext()){
          printjson(watchCursor.next());
       }

source/reference/method/db.watch.txt

@@ -254,6 +254,11 @@ have a :ref:`role <roles>` that grants the following :ref:`privilege
 The built-in :authrole:`read` role provides the appropriate
 privileges.
 
+Cursor Iteration
+----------------
+
+.. include:: /includes/fact-multiple-cursor-monitors.rst
+
 Example
 -------
 
@@ -266,17 +271,20 @@ database.
 
    watchCursor = db.getSiblingDB("hr").watch()
 
+
 Iterate the cursor to check for new events. Use the
-:method:`cursor.isExhausted()` method to ensure the loop only exits
-if the change stream cursor is closed *and* there are no objects
-remaining in the latest batch:
+:method:`cursor.isClosed()` method with the :method:`cursor.tryNext()`
+method to ensure the loop only exits if the change stream cursor is
+closed *and* there are no objects remaining in the latest batch:
 
 .. code-block:: javascript
 
-   while (!watchCursor.isExhausted()){
-      if (watchCursor.hasNext()){
-         printjson(watchCursor.next());
-      }
+   while (!watchCursor.isClosed()) {
+     let next = watchCursor.tryNext()
+     while (next !== null) {
+       printjson(next);
+       next = watchCursor.tryNext()
+     }
    }
 
 For complete documentation on change stream output, see

source/reference/method/js-cursor.txt

@@ -121,6 +121,9 @@ These methods modify the way that the underlying query is executed.
    * - :method:`cursor.toArray()`
      - Returns an array that contains all documents returned by the
        cursor.
+   * - :method:`cursor.tryNext()`
+     - Returns the next element in the iteration if available or else
+       null.
 
 .. toctree::
    :titlesonly: 
@@ -160,3 +163,4 @@ These methods modify the way that the underlying query is executed.
    /reference/method/cursor.sort
    /reference/method/cursor.tailable
    /reference/method/cursor.toArray
+   /reference/method/cursor.tryNext