Issue #808416 by lostchord, daniels220, gaurav.kapoor, jp.stacey, JacobSanford, er.pushpinderrana, jhodgdon, oriol_e9g, kiwimind, Dries: Document that clock drift will cause lock system to fail

1 files changed, 27 insertions, 8 deletions

diff --git a/core/lib/Drupal/Core/Lock/LockBackendInterface.php b/core/lib/Drupal/Core/Lock/LockBackendInterface.php
index e291295..1e6042d 100644
--- a/core/lib/Drupal/Core/Lock/LockBackendInterface.php
+++ b/core/lib/Drupal/Core/Lock/LockBackendInterface.php
@@ -5,7 +5,7 @@ namespace Drupal\Core\Lock;
 /**
  * @defgroup lock Locking mechanisms
  * @{
- * Functions to coordinate long-running operations across requests.
+ * Functions to coordinate long operations across requests.
  *
  * In most environments, multiple Drupal page requests (a.k.a. threads or
  * processes) will execute in parallel. This leads to potential conflicts or
@@ -15,15 +15,14 @@ namespace Drupal\Core\Lock;
  * problems with such code, the cron system uses a locking process to ensure
  * that cron is not started again if it is already running.
  *
- * This is a cooperative, advisory lock system. Any long-running operation
- * that could potentially be attempted in parallel by multiple requests should
- * try to acquire a lock before proceeding. By obtaining a lock, one request
- * notifies any other requests that a specific operation is in progress which
- * must not be executed in parallel.
+ * To avoid these types of conflicts, Drupal has a cooperative, advisory lock
+ * system. Any long-running operation that could potentially be attempted in
+ * parallel by multiple requests should try to acquire a lock before
+ * proceeding. By obtaining a lock, one request notifies any other requests that
+ * a specific operation is in progress which must not be executed in parallel.
  *
  * To use this API, pick a unique name for the lock. A sensible choice is the
- * name of the function performing the operation. A very simple example use of
- * this API:
+ * name of the function performing the operation. Here is a simple example:
  * @code
  * function mymodule_long_operation() {
  *   $lock = \Drupal::lock();
@@ -53,6 +52,26 @@ namespace Drupal\Core\Lock;
  * $lock->acquire() and $lock->wait() will automatically break (delete) a lock
  * whose duration has exceeded the timeout specified when it was acquired.
  *
+ * The following limitations in this implementation should be carefully noted:
+ * - Time: Timestamps are derived from the local system clock of the environment
+ *   the code is executing in. The orderly progression of time from this
+ *   viewpoint can be disrupted by external events such as NTP synchronization
+ *   and operator intervention. Where multiple web servers are involved in
+ *   serving the site, they will have their own independent clocks, introducing
+ *   another source of error in the time keeping process. Timeout values applied
+ *   to locks must therefore be considered approximate, and should not be relied
+ *   upon.
+ * - Uniqueness: Uniqueness of lock names is not enforced. The impact of the
+ *   use of a common lock name will depend on what processes and resources the
+ *   lock is being used to manage.
+ * - Sharing: There is limited support for resources shared across sites.
+ *   The locks are stored as rows in the semaphore table and, as such, they
+ *   have the same visibility as the table. If resources managed by a lock are
+ *   shared across sites then the semaphore table must be shared across sites
+ *   as well. This is a binary situation: either all resources are shared and
+ *   the semaphore table is shared or no resources are shared and the semaphore
+ *   table is not shared. Mixed mode operation is not supported.
+ *
  * @} End of "defgroup lock".
  */