summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorGabor Hojtsy2017-05-30 09:33:02 (GMT)
committerGabor Hojtsy2017-05-30 09:33:02 (GMT)
commit40e14fc21565d57d02f713b1e175e5821e3a9a25 (patch)
tree14ed24fb544f1a3da03633c40cb38f122260938e
parentd45312be489bb06044e4ae459ec92065a6cbf80b (diff)
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
-rw-r--r--core/lib/Drupal/Core/Lock/LockBackendInterface.php35
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".
*/