<?php

namespace Drupal\Core\Lock;

/**
 * @defgroup lock Locking mechanisms
 * @{
 * 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
 * race conditions when two requests execute the same code at the same time. For
 * instance, some implementations of hook_cron() implicitly assume they are
 * running only once, rather than having multiple calls in parallel. To prevent
 * problems with such code, the cron system uses a locking process to ensure
 * that cron is not started again if it is already running.
 *
 * 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. Here is a simple example:
 * @code
 * function my_module_long_operation() {
 *   $lock = \Drupal::lock();
 *   if ($lock->acquire('my_module_long_operation')) {
 *     // Do the long operation here.
 *     // ...
 *     $lock->release('my_module_long_operation');
 *   }
 * }
 * @endcode
 *
 * If a function acquires a lock it should always release it when the operation
 * is complete by calling $lock->release(), as in the example.
 *
 * A function that has acquired a lock may attempt to renew a lock (extend the
 * duration of the lock) by calling $lock->acquire() again during the operation.
 * Failure to renew a lock is indicative that another request has acquired the
 * lock, and that the current operation may need to be aborted.
 *
 * If a function fails to acquire a lock it may either immediately return, or
 * it may call $lock->wait() if the rest of the current page request requires
 * that the operation in question be complete. After $lock->wait() returns, the
 * function may again attempt to acquire the lock, or may simply allow the page
 * request to proceed on the assumption that a parallel request completed the
 * operation.
 *
 * $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".
 */

/**
 * Lock backend interface.
 *
 * @ingroup lock
 */
interface LockBackendInterface {

  /**
   * Acquires a lock.
   *
   * @param string $name
   *   Lock name. Limit of name's length is 255 characters.
   * @param float $timeout
   *   (optional) Lock lifetime in seconds. Defaults to 30.0.
   *
   * @return bool
   */
  public function acquire($name, $timeout = 30.0);

  /**
   * Checks if a lock is available for acquiring.
   *
   * @param string $name
   *   Lock to acquire.
   *
   * @return bool
   */
  public function lockMayBeAvailable($name);

  /**
   * Waits a short amount of time before a second lock acquire attempt.
   *
   * While this method is subject to have a generic implementation in abstract
   * backend implementation, some backends may provide non blocking or less I/O
   * intensive wait mechanism: this is why this method remains on the backend
   * interface.
   *
   * @param string $name
   *   Lock name currently being locked.
   * @param int $delay
   *   Seconds to wait for. Defaults to 30.
   *
   * @return bool
   *   TRUE if the lock holds, FALSE if it may be available. You still need to
   *   acquire the lock manually and it may fail again.
   */
  public function wait($name, $delay = 30);

  /**
   * Releases the given lock.
   *
   * @param string $name
   *   The lock name.
   */
  public function release($name);

  /**
   * Releases all locks for the given lock token identifier.
   *
   * @param string $lockId
   *   (optional) If none given, remove all locks from the current page.
   *   Defaults to NULL.
   */
  public function releaseAll($lockId = NULL);

  /**
   * Gets the unique page token for locks.
   *
   * Locks will be wiped out at the end of each page request on a token basis.
   *
   * @return string
   */
  public function getLockId();

}