Locking mechanisms

Functions to coordinate long-running 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. A common example of this is a rebuild like menu_rebuild() where we invoke many hook implementations to get and process data from all active modules, and then delete the current data in the database to insert the new afterwards.

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 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:

function mymodule_long_operation() {
  if (lock_acquire('mymodule_long_operation')) {

    // Do the long operation here.
    // ...
    lock_release('mymodule_long_operation');
  }
}

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.

Alternative implementations of this API (such as APC) may be substituted by setting the 'lock_inc' variable to an alternate include filepath. Since this is an API intended to support alternative implementations, code using this API should never rely upon specific implementation details (for example no code should look for or directly modify a lock in the {semaphore} table).

File

drupal/includes/lock.inc, line 8

A database-mediated implementation of a locking mechanism.

Functions

Name	Location	Description
lock_initialize	drupal/includes/lock.inc	Initialize the locking system.
_lock_id	drupal/includes/lock.inc	Helper function to get this request's unique id.
lock_acquire	drupal/includes/lock.inc	Acquire (or renew) a lock, but do not block if it fails.
lock_may_be_available	drupal/includes/lock.inc	Check if lock acquired by a different process may be available.
lock_wait	drupal/includes/lock.inc	Wait for a lock to be available.
lock_release	drupal/includes/lock.inc	Release a lock previously acquired by lock_acquire().
lock_release_all	drupal/includes/lock.inc	Release all previously acquired locks.