DOCS-1919: document maxTimeMS

source/includes/ref-toc-method-cursor.yaml

@@ -34,6 +34,10 @@ name: ":method:`cursor.map()`"
 file: /reference/method/cursor.map
 description: "Applies a function to each document in a cursor and collects the return values in an array."
 ---
+name: ":method:`cursor.maxTimeMS()`"
+file: /reference/method/cursor.maxTimeMS
+description: "Specifies a cumulative time limit in milliseconds for processing operations on a cursor."
+---
 name: ":method:`cursor.max()`"
 file: /reference/method/cursor.max
 description: "Specifies an exclusive upper index bound for a cursor. For use with :method:`cursor.hint()`"
@@ -77,4 +81,4 @@ description: "Returns results ordered according to a sort specification."
 name: ":method:`cursor.toArray()`"
 file: /reference/method/cursor.toArray
 description: "Returns an array that contains all documents returned by the cursor."
-...
+...

source/includes/ref-toc-operator-meta.yaml

@@ -14,6 +14,10 @@ name: ":operator:`$maxScan`"
 file: /reference/operator/meta/maxScan
 description: "Limits the number of documents a cursor will return for a query. See :method:`~cursor.limit()`."
 ---
+name: ":operator:`$maxTimeMS`"
+file: /reference/operator/meta/maxTimeMS
+description: "Specifies a cumulative time limit in milliseconds for processing operations on a cursor. See :method:`~cursor.maxTimeMS()`."
+---
 name: ":operator:`$max`"
 file: /reference/operator/meta/max
 description: "Specifies a minimum exclusive upper limit for the index to use in a query. See :method:`~cursor.max()`."

source/reference/glossary.txt

@@ -330,6 +330,12 @@ Glossary
      The international date format used by :program:`mongo`
      to display dates. The format is: ``YYYY-MM-DD HH:MM.SS.millis``.
 
+   Interrupt Point
+     A time in an operation's lifecycle when it can
+     safely abort. MongoDB only terminates an operation
+     at one of its designated interrupt points. See
+     :doc:`/tutorial/terminate-running-operations`.
+
    JavaScript
       A popular scripting language originally designed for web
       browsers. The MongoDB shell and certain server-side functions use

source/reference/method/cursor.maxTimeMS-param.yaml

@@ -0,0 +1,13 @@
+object:
+  name: cursor.maxTimeMS()
+  type: method
+field:
+  optional: false
+  type: param
+name: milliseconds
+type: integer
+position: 1
+description: |
+  Specifies a cumulative time limit in milliseconds for processing operations
+  on the cursor.
+...

source/reference/method/cursor.maxTimeMS.txt

@@ -0,0 +1,50 @@
+==================
+cursor.maxTimeMS()
+==================
+
+.. default-domain:: mongodb
+
+Definition
+----------
+
+.. versionadded:: 2.5.4
+
+.. method:: cursor.maxTimeMS(<time limit>)
+
+   Specifies a cumulative time limit in milliseconds for processing
+   operations on a cursor.
+
+   The :method:`~cursor.maxTimeMS()` method has the following
+   parameter:
+
+   .. include:: /reference/method/cursor.maxTimeMS-param.rst
+
+.. important::
+
+   :method:`~cursor.maxTimeMS()` is not related to the
+   ``NoCursorTimeout`` query flag. :method:`~cursor.maxTimeMS()`
+   relates to processing time, while ``NoCursorTimeout`` relates
+   to idle time. A cursor's idle time does not contribute towards its
+   processing time.
+
+Behaviors
+---------
+
+MongoDB targets operations for termination if the associated cursor
+exceeds its allotted time limit. MongoDB only terminates an operation
+at one of its designated interrupt points.
+
+MongoDB does not count network latency towards a cursor's time limit.
+
+Queries that generate multiple batches of results continue to return
+batches until the cursor exceeds its allotted time limit.
+
+Examples
+--------
+
+.. example:: The following query specifies a time limit of 50 milliseconds:
+
+   .. code-block:: javascript
+
+      db.collection.find({description: /August [0-9]+, 1969/}).maxTimeMS(50)
+

source/reference/method/db.runCommand.txt

@@ -15,3 +15,8 @@ Definition
    the shell and drivers.
 
    .. include:: /reference/method/db.runCommand-param.rst
+
+   .. versionadded:: 2.5.4
+      To specify a time limit in milliseconds, see
+      :doc:`/tutorial/terminate-running-operations`.
+

source/reference/operator/meta/maxTimeMS.txt

@@ -0,0 +1,34 @@
+==========
+$maxTimeMS
+==========
+
+.. default-domain:: mongodb
+
+.. operator:: $maxTimeMS
+
+   .. versionadded:: 2.5.4
+      The :operator:`$maxTimeMS` operator specifies a cumulative
+      time limit in milliseconds for processing operations on the
+      cursor. MongoDB interrupts the operation at the earliest
+      following :term:`interrupt point`.
+
+   The :program:`mongo` shell provides the :method:`cursor.maxTimeMS()` method
+
+   .. code-block:: javascript
+
+      db.collection.find().maxTimeMS(100)
+
+   You can also specify the option in either of the following forms:
+
+   .. code-block:: javascript
+
+      db.collection.find( $query: { } , $maxTimeMS: 100 } )
+      db.collection.find()._addSpecial("$maxTimeMS", 100)
+
+   Interrupted operations return an error message similar to the
+   following:
+
+   .. code-block:: javascript
+
+      error: { "$err" : "operation exceeded time limit", "code" : 50 }
+

source/tutorial/terminate-running-operations.txt

@@ -0,0 +1,65 @@
+============================
+Terminate Running Operations
+============================
+
+.. default-domain:: mongodb
+
+Available Procedures
+--------------------
+
+``maxTimeMS``
+~~~~~~~~~~~~~
+
+.. versionadded:: 2.5.4
+
+The :method:`~cursor.maxTimeMS()` method sets a time limit for an
+operation. When the operation reaches the specified time limit,
+MongoDB interrupts the operation at the next :term:`interrupt point`.
+
+Terminate a Query
+`````````````````
+
+From the :program:`mongo` shell, use the following method to set a time limit of
+30 milliseconds for this query:
+
+.. code-block:: javascript
+
+   db.location.find({"town": { "$regex": "(Pine Bush)", "$options": 'i' }}).maxTimeMS(30)
+
+Terminate a Command
+```````````````````
+
+Given a query that uses the :method:`~db.runCommand()` command to
+return each distinct ``collection`` field that has a ``city`` key:
+
+.. code-block:: javascript
+
+   db.runCommand( { distinct: "collection", key: "city" } )
+
+From the :program:`mongo` shell, add the ``maxTimeMS``
+field to set a time limit of 30 milliseconds for the query:
+
+.. code-block:: javascript
+
+   db.runCommand( { distinct: "collection", key: "city", maxTimeMS: 45 } )
+
+Interrupted operations produce an error reportable by
+:method:`db.getLastError()`:
+
+.. code-block:: javascript
+
+   { "n" : 0, "connectionId" : 1, "err" : "operation exceeded time limit", "ok" : 1 }
+
+``killOp``
+~~~~~~~~~~
+
+The :method:`db.killOp()` method interrupts a running operation at
+the next :term:`interrupt point`. :method:`db.killOp()` identifies
+the target operation by operation ID.
+
+.. code-block:: javascript
+
+   db.killOp(<opId>)
+
+See :method:`db.currentOp()`.
+