DOCSP-11906 find and modify atomicity (#661) (#707)

* DOCSP-11906-find-and-modify-atomicity

* DOCSP-11906-find-and-modify-atomicity

* DOCSP-11906-find-and-modify-atomicity

* DOCSP-11906-find-and-modify-atomicity

* DOCSP-11906-find-and-modify-atomicity

* DOCSP-11906-find-and-modify-atomicity

* DOCSP-11906-find-and-modify-atomicity

* DOCSP-11906-find-and-modify-atomicity

Co-authored-by: jason-price-mongodb <[email protected]>

Co-authored-by: jason-price-mongodb <[email protected]>

Author: jason-price-mongodb

source/core/write-operations-atomicity.txt

@@ -34,16 +34,46 @@ Concurrency Control
 Concurrency control allows multiple applications to run concurrently
 without causing data inconsistency or conflicts.
 
-One approach is to create a :ref:`unique index <index-type-unique>` on a
-field that can only have unique values. This prevents insertions or
-updates from creating duplicate data. Create a unique index on multiple
-fields to force uniqueness on that combination of field values. For
-examples of use cases, see :ref:`update() and Unique Index
-<update-with-unique-indexes>` and :ref:`findAndModify() and Unique Index
-<upsert-and-unique-index>`.
+A :dbcommand:`findAndModify` operation on a document is :term:`atomic
+<atomic operation>`: if the find condition matches a document, the
+update is performed on that document. Concurrent queries and additional
+updates on that document are not affected until the current update is
+complete.
+
+Consider the following example:
+
+- A collection with two documents:
+
+  .. code-block:: javascript
+
+     db.myCollection.insertMany( [
+        { _id: 0, a: 1, b: 1 },
+        { _id: 1, a: 1, b: 1 }
+     ] )
+
+- Two of the following :dbcommand:`findAndModify` operations run
+  concurrently:
+
+  .. code-block:: javascript
 
-Another approach is to specify the expected current value of a field in
-the query predicate for the write operations.
+     db.myCollection.findAndModify( {
+        query: { a: 1 },
+        update: { $inc: { b: 1 }, $set: { a: 2 } }
+     } )
+
+After the :dbcommand:`findAndModify` operations are complete, it is
+guaranteed that ``a`` and ``b`` in both documents are set to ``2``.
+
+.. seealso::
+
+   :ref:`findAndModify() Upsert Example <findAndModify-upsert-example>`
+
+You can also create a :ref:`unique index <index-type-unique>` on a field
+so that it can only have unique values. This prevents inserts and
+updates from creating duplicate data. You can create a unique index
+on multiple fields to ensure the combination of field values is unique.
+For an example, see :ref:`findAndModify() Upsert with Unique Index
+<upsert-and-unique-index>`.
 
 .. seealso::
 

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

@@ -434,6 +434,8 @@ This method performs the following actions:
    If no document matched the ``query`` condition, the method
    returns ``null``.
 
+.. _findAndModify-upsert-example:
+
 Upsert
 ~~~~~~