DOCSP-7387 Lock free reads

Author: jason-price-mongodb

source/faq/concurrency.txt

@@ -10,13 +10,11 @@ FAQ: Concurrency
    :depth: 1
    :class: twocols
 
-MongoDB allows multiple clients to read and write the same data.
-In order to ensure consistency, it uses locking and other
-:term:`concurrency control` measures to prevent multiple clients
-from modifying the same piece of data simultaneously.
-Together, these mechanisms guarantee that all writes to a single
-document occur either in full or not at all and that clients never
-see an inconsistent view of the data.
+MongoDB allows multiple clients to read and write the same data. To
+ensure consistency, MongoDB uses locking and :term:`concurrency control`
+to prevent clients from modifying the same data simultaneously. Writes
+to a single document occur either in full or not at all, and clients
+always see consistent data.
 
 .. _faq-dev-concurrency:
 .. _faq-concurrency-locking:
@@ -29,24 +27,24 @@ What type of locking does MongoDB use?
 In addition to a shared (S) locking mode for reads and an exclusive
 (X) locking mode for write operations, intent shared (IS) and intent
 exclusive (IX) modes indicate an intent to read or write a resource
-using a finer granularity lock.  When locking at a certain granularity,
+using a finer granularity lock. When locking at a certain granularity,
 all higher levels are locked using an :term:`intent lock`.
 
 For example, when locking a collection for writing (using mode X),
 both the corresponding database lock and the global lock must be
 locked in intent exclusive (IX) mode. A single database can
 simultaneously be locked in IS and IX mode, but an exclusive (X)
 lock cannot coexist with any other modes, and a shared (S) lock can
-only coexists with intent shared (IS) locks.
+only coexist with intent shared (IS) locks.
 
 .. |rarr| unicode:: 0x2192 .. right arrow
 
-Locks are fair, with reads and writes being queued in order. However,
-to optimize throughput, when one request is granted, all other
-compatible requests will be granted at the same time, potentially
-releasing them before a conflicting request.  For example, consider
-a case in which an X lock was just released, and in which the
-conflict queue contains the following items:
+Locks are fair, with lock requests for reads and writes queued in order.
+However, to optimize throughput, when one lock request is granted, all
+other compatible lock requests are granted at the same time, potentially
+releasing the locks before a conflicting lock request is performed. For
+example, consider a situation where an X lock was just released and the
+conflict queue contains these locks:
 
 IS |rarr| IS |rarr| X |rarr| X |rarr| S |rarr| IS
 
@@ -75,8 +73,8 @@ How granular are locks in MongoDB?
 How do I see the status of locks on my :binary:`~bin.mongod` instances?
 -----------------------------------------------------------------------
 
-For reporting on lock utilization information on locks, use any of the
-following methods:
+For reporting on lock utilization information on locks, use any of these
+methods:
 
 - :method:`db.serverStatus()`,
 - :method:`db.currentOp()`,
@@ -110,7 +108,7 @@ Does a read or write operation ever yield the lock?
 In some situations, read and write operations can yield their locks.
 
 Long running read and write operations, such as queries, updates,
-and deletes, yield under many conditions.  MongoDB operations can
+and deletes, yield locks under many conditions. MongoDB operations can
 also yield locks between individual document modifications in write
 operations that affect multiple documents like
 :method:`~db.collection.update()` with the ``multi`` parameter.
@@ -209,15 +207,16 @@ use for document level locking storage engines:
 Which administrative commands lock the database?
 ------------------------------------------------
 
-Certain administrative commands can exclusively lock the database for
-extended periods of time. In some deployments, for large databases,
-you may consider taking the :binary:`~bin.mongod` instance offline so that
-clients are not affected. For example, if a :binary:`~bin.mongod` is part
-of a :term:`replica set`, take the :binary:`~bin.mongod` offline and let
-other members of the set service load while maintenance is in progress.
+Some administrative commands can exclusively lock the database for
+extended time periods. For large database deployments, you may consider
+taking the :binary:`~bin.mongod` instance offline so that clients are
+not affected. For example, if a :binary:`~bin.mongod` is part of a
+:term:`replica set`, take the :binary:`~bin.mongod` offline and let
+other members of the replica set process requests while maintenance is
+performed.
 
-The following administrative operations require an exclusive
-lock at the database level for extended periods:
+These administrative operations require an exclusive lock at the
+database level for extended periods:
 
 .. list-table::
    :header-rows: 1
@@ -261,7 +260,7 @@ lock at the database level for extended periods:
          exclusive (W) lock when renaming a collection across
          databases and blocks other operations until it finishes.
 
-The following administrative operations lock the database but only hold
+These administrative operations lock the database but only hold
 the lock for a very short time:
 
 .. list-table::
@@ -289,8 +288,8 @@ Which administrative commands lock a collection?
 
 .. versionchanged:: 4.2
 
-The following administrative operations require an exclusive lock at
-the collection level:
+These administrative operations require an exclusive lock at the
+collection level:
 
 .. list-table::
    :header-rows: 1
@@ -375,8 +374,8 @@ until the operation completed.
 Does a MongoDB operation ever lock more than one database?
 ----------------------------------------------------------
 
-The following MongoDB operations may obtain and hold a lock on more 
-than one database:
+These MongoDB operations may obtain and hold a lock on more than one
+database:
 
 .. list-table::
    :header-rows: 1
@@ -429,10 +428,9 @@ How does sharding affect concurrency?
 -------------------------------------
 
 :term:`Sharding <sharding>` improves concurrency by distributing
-collections over multiple :binary:`~bin.mongod` instances, allowing shard
-servers (i.e. :binary:`~bin.mongos` processes) to perform any number of
-operations concurrently to the various downstream :binary:`~bin.mongod`
-instances.
+collections over multiple :binary:`~bin.mongod` instances, allowing
+shard servers (specifically, :binary:`~bin.mongos` processes) to run
+concurrently with the downstream :binary:`~bin.mongod` instances.
 
 .. include:: /includes/extracts/lock-sharding.rst
 
@@ -447,7 +445,7 @@ which is a special collection in the ``local`` database. Therefore,
 MongoDB must lock both the collection's database and the ``local``
 database. The :binary:`~bin.mongod` must lock both databases at the same
 time to keep the database consistent and ensure that write operations,
-even with replication, are "all-or-nothing" operations.
+even with replication, are all or nothing operations.
 
 .. include:: /includes/extracts/lock-replica-set-primary.rst
 
@@ -483,6 +481,18 @@ Depending on the read concern, clients can see the results of writes
 before the writes are :term:`durable`. To control whether the data read
 may be rolled back or not, clients can use the ``readConcern`` option.
 
+.. _faq-concurrency-lock-free-read-operations:
+
+What are lock-free read operations?
+-----------------------------------
+
+.. versionadded:: 5.0
+
+A lock-free read operation runs immediately: it is not blocked when
+another operation has an exclusive (X) write lock on the collection.
+
+.. include:: /includes/lock-free-commands.rst
+
 For information, see:
 
 - :doc:`/core/read-isolation-consistency-recency`

source/includes/lock-free-commands.rst

@@ -0,0 +1,23 @@
+Starting in MongoDB 5.0, the following read operations are not blocked
+when another operation holds an exclusive (X) write lock on the
+collection:
+
+- :dbcommand:`find`
+
+- :dbcommand:`count`
+
+- :dbcommand:`distinct`
+
+- :dbcommand:`aggregate`
+
+- :dbcommand:`mapReduce`
+
+- :dbcommand:`listCollections`
+
+- :dbcommand:`listIndexes`
+
+When writing to a collection, :dbcommand:`mapReduce` and
+:dbcommand:`aggregate` hold an intent exclusive (IX) lock. Therefore, if
+an exclusive X lock is already held on a collection,
+:dbcommand:`mapReduce` and :dbcommand:`aggregate` write operations are
+blocked.