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

* 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/security-transport-encryption.txt

@@ -226,6 +226,8 @@ For more information, see:
 
 - :doc:`/tutorial/configure-x509-member-authentication`
 
+.. _fips-mode:
+
 FIPS Mode
 ---------
 

source/core/write-operations-atomicity.txt

@@ -32,15 +32,44 @@ 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 atomic: 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:
 
-Another approach is to specify the expected current value of a field in
-the query predicate for the write operations.
+  .. code-block:: javascript
+
+     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:: :doc:`/core/read-isolation-consistency-recency`

source/includes/md5-and-scram-sha-1.rst

@@ -3,7 +3,7 @@ If you use :ref:`SCRAM-SHA-1 <authentication-scram-sha-1>`:
 - :term:`md5` is necessary but is not used for cryptographic purposes,
   and
 
-- if you use :ref:`FIPS mode <fips-overview>`, then instead of
+- if you use :ref:`FIPS mode <fips-mode>`, then instead of
   :ref:`SCRAM-SHA-1 <authentication-scram-sha-1>` use:
 
   - :ref:`SCRAM-SHA-256 <authentication-scram-sha-256>`,

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

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