Same name in this branch
  1. 6.x includes/lock.inc \lock_acquire()
  2. 6.x includes/lock-install.inc \lock_acquire()
Same name and namespace in other branches
  1. 7.x includes/lock.inc \lock_acquire()

Acquire (or renew) a lock, but do not block if it fails.

Parameters

$name: The name of the lock.

$timeout: A number of seconds (float) before the lock expires.

Return value

TRUE if the lock was acquired, FALSE if it failed.

Related topics

File

includes/lock.inc, line 96
A database-mediated implementation of a locking mechanism.

Code

function lock_acquire($name, $timeout = 30.0) {
  global $locks;

  // Insure that the timeout is at least 1 ms.
  $timeout = max($timeout, 0.001);
  list($usec, $sec) = explode(' ', microtime());
  $expire = (double) $usec + (double) $sec + $timeout;
  if (isset($locks[$name])) {

    // Try to extend the expiration of a lock we already acquired.
    db_query("UPDATE {semaphore} SET expire = %f WHERE name = '%s' AND value = '%s'", $expire, $name, _lock_id());
    if (!db_affected_rows()) {

      // The lock was broken.
      unset($locks[$name]);
    }
  }
  else {

    // Optimistically try to acquire the lock, then retry once if it fails.
    // The first time through the loop cannot be a retry.
    $retry = FALSE;

    // We always want to do this code at least once.
    do {
      if (@db_query("INSERT INTO {semaphore} (name, value, expire) VALUES ('%s', '%s', %f)", $name, _lock_id(), $expire)) {

        // We track all acquired locks in the global variable.
        $locks[$name] = TRUE;

        // We never need to try again.
        $retry = FALSE;
      }
      else {

        // Suppress the error. If this is our first pass through the loop,
        // then $retry is FALSE. In this case, the insert must have failed
        // meaning some other request acquired the lock but did not release it.
        // We decide whether to retry by checking lock_may_be_available()
        // Since this will break the lock in case it is expired.
        $retry = $retry ? FALSE : lock_may_be_available($name);
      }

      // We only retry in case the first attempt failed, but we then broke
      // an expired lock.
    } while ($retry);
  }
  return isset($locks[$name]);
}