Chris@0: <?php
Chris@0: 
Chris@0: namespace Drupal\Core\Lock;
Chris@0: 
Chris@0: /**
Chris@0:  * @defgroup lock Locking mechanisms
Chris@0:  * @{
Chris@0:  * Functions to coordinate long operations across requests.
Chris@0:  *
Chris@0:  * In most environments, multiple Drupal page requests (a.k.a. threads or
Chris@0:  * processes) will execute in parallel. This leads to potential conflicts or
Chris@0:  * race conditions when two requests execute the same code at the same time. For
Chris@0:  * instance, some implementations of hook_cron() implicitly assume they are
Chris@0:  * running only once, rather than having multiple calls in parallel. To prevent
Chris@0:  * problems with such code, the cron system uses a locking process to ensure
Chris@0:  * that cron is not started again if it is already running.
Chris@0:  *
Chris@0:  * To avoid these types of conflicts, Drupal has a cooperative, advisory lock
Chris@0:  * system. Any long-running operation that could potentially be attempted in
Chris@0:  * parallel by multiple requests should try to acquire a lock before
Chris@0:  * proceeding. By obtaining a lock, one request notifies any other requests that
Chris@0:  * a specific operation is in progress which must not be executed in parallel.
Chris@0:  *
Chris@0:  * To use this API, pick a unique name for the lock. A sensible choice is the
Chris@0:  * name of the function performing the operation. Here is a simple example:
Chris@0:  * @code
Chris@0:  * function mymodule_long_operation() {
Chris@0:  *   $lock = \Drupal::lock();
Chris@0:  *   if ($lock->acquire('mymodule_long_operation')) {
Chris@0:  *     // Do the long operation here.
Chris@0:  *     // ...
Chris@0:  *     $lock->release('mymodule_long_operation');
Chris@0:  *   }
Chris@0:  * }
Chris@0:  * @endcode
Chris@0:  *
Chris@0:  * If a function acquires a lock it should always release it when the operation
Chris@0:  * is complete by calling $lock->release(), as in the example.
Chris@0:  *
Chris@0:  * A function that has acquired a lock may attempt to renew a lock (extend the
Chris@0:  * duration of the lock) by calling $lock->acquire() again during the operation.
Chris@0:  * Failure to renew a lock is indicative that another request has acquired the
Chris@0:  * lock, and that the current operation may need to be aborted.
Chris@0:  *
Chris@0:  * If a function fails to acquire a lock it may either immediately return, or
Chris@0:  * it may call $lock->wait() if the rest of the current page request requires
Chris@0:  * that the operation in question be complete. After $lock->wait() returns, the
Chris@0:  * function may again attempt to acquire the lock, or may simply allow the page
Chris@0:  * request to proceed on the assumption that a parallel request completed the
Chris@0:  * operation.
Chris@0:  *
Chris@0:  * $lock->acquire() and $lock->wait() will automatically break (delete) a lock
Chris@0:  * whose duration has exceeded the timeout specified when it was acquired.
Chris@0:  *
Chris@0:  * The following limitations in this implementation should be carefully noted:
Chris@0:  * - Time: Timestamps are derived from the local system clock of the environment
Chris@0:  *   the code is executing in. The orderly progression of time from this
Chris@0:  *   viewpoint can be disrupted by external events such as NTP synchronization
Chris@0:  *   and operator intervention. Where multiple web servers are involved in
Chris@0:  *   serving the site, they will have their own independent clocks, introducing
Chris@0:  *   another source of error in the time keeping process. Timeout values applied
Chris@0:  *   to locks must therefore be considered approximate, and should not be relied
Chris@0:  *   upon.
Chris@0:  * - Uniqueness: Uniqueness of lock names is not enforced. The impact of the
Chris@0:  *   use of a common lock name will depend on what processes and resources the
Chris@0:  *   lock is being used to manage.
Chris@0:  * - Sharing: There is limited support for resources shared across sites.
Chris@0:  *   The locks are stored as rows in the semaphore table and, as such, they
Chris@0:  *   have the same visibility as the table. If resources managed by a lock are
Chris@0:  *   shared across sites then the semaphore table must be shared across sites
Chris@0:  *   as well. This is a binary situation: either all resources are shared and
Chris@0:  *   the semaphore table is shared or no resources are shared and the semaphore
Chris@0:  *   table is not shared. Mixed mode operation is not supported.
Chris@0:  *
Chris@0:  * @} End of "defgroup lock".
Chris@0:  */
Chris@0: 
Chris@0: /**
Chris@0:  * Lock backend interface.
Chris@0:  *
Chris@0:  * @ingroup lock
Chris@0:  */
Chris@0: interface LockBackendInterface {
Chris@0: 
Chris@0:   /**
Chris@0:    * Acquires a lock.
Chris@0:    *
Chris@0:    * @param string $name
Chris@0:    *   Lock name. Limit of name's length is 255 characters.
Chris@0:    * @param float $timeout
Chris@0:    *   (optional) Lock lifetime in seconds. Defaults to 30.0.
Chris@0:    *
Chris@0:    * @return bool
Chris@0:    */
Chris@0:   public function acquire($name, $timeout = 30.0);
Chris@0: 
Chris@0:   /**
Chris@0:    * Checks if a lock is available for acquiring.
Chris@0:    *
Chris@0:    * @param string $name
Chris@0:    *   Lock to acquire.
Chris@0:    *
Chris@0:    * @return bool
Chris@0:    */
Chris@0:   public function lockMayBeAvailable($name);
Chris@0: 
Chris@0:   /**
Chris@0:    * Waits a short amount of time before a second lock acquire attempt.
Chris@0:    *
Chris@0:    * While this method is subject to have a generic implementation in abstract
Chris@0:    * backend implementation, some backends may provide non blocking or less I/O
Chris@0:    * intensive wait mechanism: this is why this method remains on the backend
Chris@0:    * interface.
Chris@0:    *
Chris@0:    * @param string $name
Chris@0:    *   Lock name currently being locked.
Chris@0:    * @param int $delay
Chris@0:    *   Seconds to wait for. Defaults to 30.
Chris@0:    *
Chris@0:    * @return bool
Chris@0:    *   TRUE if the lock holds, FALSE if it may be available. You still need to
Chris@0:    *   acquire the lock manually and it may fail again.
Chris@0:    */
Chris@0:   public function wait($name, $delay = 30);
Chris@0: 
Chris@0:   /**
Chris@0:    * Releases the given lock.
Chris@0:    *
Chris@0:    * @param string $name
Chris@0:    */
Chris@0:   public function release($name);
Chris@0: 
Chris@0:   /**
Chris@0:    * Releases all locks for the given lock token identifier.
Chris@0:    *
Chris@0:    * @param string $lockId
Chris@0:    *   (optional) If none given, remove all locks from the current page.
Chris@0:    *   Defaults to NULL.
Chris@0:    */
Chris@0:   public function releaseAll($lockId = NULL);
Chris@0: 
Chris@0:   /**
Chris@0:    * Gets the unique page token for locks.
Chris@0:    *
Chris@0:    * Locks will be wiped out at the end of each page request on a token basis.
Chris@0:    *
Chris@0:    * @return string
Chris@0:    */
Chris@0:   public function getLockId();
Chris@0: 
Chris@0: }