DOCS-11716: maxTransactionLockRequestTimeoutMillis

Author: kay-kim

source/core/transactions-production-consideration.txt

@@ -44,3 +44,18 @@ To prevent storage cache pressure from immobilizing the system:
 
 The :parameter:`transactionLifetimeLimitSeconds` also ensures that
 expired transactions are aborted periodically.
+
+Lock Request Timeout
+--------------------
+
+By default, transactions waits ``5`` milliseconds to acquire locks
+required by the operations in the transaction. If the transaction
+cannot acquire its required locks within the ``5`` milliseconds, the
+transaction aborts.
+
+Increasing :parameter:`maxTransactionLockRequestTimeoutMillis` allows
+operations in the transactions to wait the specified time to acquire
+the required locks. This can help obviate transaction abortion on
+momentary concurrent lock acquisitions, like fast-running metadata
+operations. However, this could possibly delay the abort of deadlocked
+transaction operations.

source/core/transactions.txt

@@ -73,8 +73,8 @@ engine, you must set :rsconf:`writeConcernMajorityJournalDefault` to
 
 .. _transactions-operations:
 
-Transactions and CRUD Operations
---------------------------------
+Transactions and Operations
+---------------------------
 
 For multi-document transactions:
 
@@ -124,6 +124,22 @@ Transactions and Security
 - If running with :doc:`auditing </core/auditing>`, operations in an
   aborted transaction are still audited.
 
+Transactions and Locks
+----------------------
+
+By default, transactions waits ``5`` milliseconds to acquire locks
+required by the operations in the transaction. If the transaction
+cannot acquire its required locks within the ``5`` milliseconds, the
+transaction aborts.
+
+You can use the :parameter:`maxTransactionLockRequestTimeoutMillis`
+parameter to adjust how long transactions wait to acquire locks.
+
+You can also use operation-specific timeout by setting
+:parameter:`maxTransactionLockRequestTimeoutMillis` to ``-1``.
+
+Transactions release all locks upon abort.
+
 Transactions and Sessions
 -------------------------
 
@@ -165,22 +181,6 @@ transactions:
 
 - :method:`Session.abortTransaction()`
 
-Atomicity
----------
-
-Multi-document transactions are atomic:
-
-- When a transaction commits, all data changes made in the transaction
-  are saved and visible outside the transaction. Until a transaction
-  commits, the data changes made in the transaction are not visible
-  outside the transaction.
-
-- When a transaction aborts, all data changes made in the transaction
-  are discarded without ever becoming visible. For example, if any
-  operation in the transaction fails, the transaction aborts and all
-  data changes made in the transaction are discarded without ever
-  becoming visible.
-
 .. _transactions-retry:
 
 Transactions and Retryable Writes
@@ -354,6 +354,22 @@ and retrying the commit, the full code example is:
       session.endSession();
    }
 
+Atomicity
+---------
+
+Multi-document transactions are atomic:
+
+- When a transaction commits, all data changes made in the transaction
+  are saved and visible outside the transaction. Until a transaction
+  commits, the data changes made in the transaction are not visible
+  outside the transaction.
+
+- When a transaction aborts, all data changes made in the transaction
+  are discarded without ever becoming visible. For example, if any
+  operation in the transaction fails, the transaction aborts and all
+  data changes made in the transaction are discarded without ever
+  becoming visible.
+
 Read Preference
 ---------------
 

source/reference/parameters.txt

@@ -1233,6 +1233,59 @@ Logical Session Parameters
 
    .. seealso:: :parameter:`localLogicalSessionTimeoutMinutes`
 
+.. parameter:: maxTransactionLockRequestTimeoutMillis
+
+   .. versionadded:: 4.0
+
+   |mongod-only|
+
+   *Type*: integer
+
+   *Default*: 5
+
+   The amount of time in milliseconds that :doc:`multi-document
+   transactions </core/transactions>` should wait to aquire locks
+   required by the operations in the transaction.
+
+   If the transaction cannot aquire the locks after waiting
+   :parameter:`maxTransactionLockRequestTimeoutMillis`, the transaction
+   aborts.
+
+   By default, :doc:`multi-document transactions </core/transactions>`
+   wait ``5`` milliseconds. That is, if the transaction cannot acquire
+   the locks within ``5`` milliseconds, the transaction aborts. If an
+   operation provides a greater timeout in a lock request,
+   :parameter:`maxTransactionLockRequestTimeoutMillis` overrides the
+   operation-specific timeout.
+
+   You can set :parameter:`maxTransactionLockRequestTimeoutMillis` to:
+
+   - ``0`` such that if the transaction cannot acquire the required
+     locks immediately, the transaction aborts.
+
+   - A number greater than ``0`` to wait the specified time to acquire
+     the required locks. This can help obviate transaction abortion on
+     momentary concurrent lock acquisitions, like fast-running metadata
+     operations. However, this could possibly delay the abort of
+     deadlocked transaction operations.
+
+   - ``-1`` to use the operation specific timeout.
+
+   The following sets the
+   :parameter:`maxTransactionLockRequestTimeoutMillis` to ``20``
+   milliseconds:
+
+   .. code-block:: javascript
+
+      db.adminCommand( { setParameter: 1, maxTransactionLockRequestTimeoutMillis: 20 } )
+
+   You can also set this parameter during start-up:
+
+   .. code-block:: sh
+
+      mongod --setParameter maxTransactionLockRequestTimeoutMillis=20
+
+
 Replication Parameters
 ~~~~~~~~~~~~~~~~~~~~~~
 

source/release-notes/4.0.txt

@@ -97,6 +97,19 @@ Commands
      Use the corresponding driver method or :binary:`~bin.mongo` shell
      helper :method:`Session.commitTransaction()` instead.
 
+Locks
+~~~~~
+
+By default, :doc:`multi-document transactions </core/transactions>`
+wait ``5`` milliseconds to acquire locks required by the operations in
+the transaction. If the transaction cannot acquire its required locks
+with the ``5`` milliseconds, the transaction aborts.
+
+You can use the :parameter:`maxTransactionLockRequestTimeoutMillis`
+parameter to adjust how long transactions wait to acquire locks.
+
+Transactions release all locks upon abort or commit.
+
 ``$currentOp``
 ~~~~~~~~~~~~~~
 
@@ -108,10 +121,14 @@ which are holding locks as part of a transaction.
 Parameters
 ~~~~~~~~~~
 
-:parameter:`transactionLifetimeLimitSeconds` to specify the lifetime
-for a :doc:`multi-document transaction </core/transactions>` after
-which the transaction is considered expired and will be aborted when
-the periodic cleanup process next runs.
+- :parameter:`transactionLifetimeLimitSeconds` to specify the lifetime
+  for a :doc:`multi-document transaction </core/transactions>` after
+  which the transaction is considered expired and will be aborted when
+  the periodic cleanup process next runs.
+
+- :parameter:`maxTransactionLockRequestTimeoutMillis` to specify how
+  long :doc:`multi-document transactions </core/transactions>` should
+  wait to aquire locks required by the operations in the transaction.
 
 Aggregation
 -----------