final class PhabricatorGlobalLock
Phorge Technical Documentation ()

Global, MySQL-backed lock. This is a high-reliability, low-performance global lock.

The lock is maintained by using GET_LOCK() in MySQL, and automatically released when the connection terminates. Thus, this lock can safely be used to control access to shared resources without implementing any sort of timeout or override logic: the lock can't normally be stuck in a locked state with no process actually holding the lock.

However, acquiring the lock is moderately expensive (several network roundtrips). This makes it unsuitable for tasks where lock performance is important.

$lock = PhabricatorGlobalLock::newLock('example');
$lock->lock();
  do_contentious_things();
$lock->unlock();

NOTE: This lock is not completely global; it is namespaced to the active storage namespace so that unit tests running in separate table namespaces are isolated from one another.

Tasks

Implementation

protected function doLock($wait)
protected function doUnlock()

Lock Registry

final public function getName() — Returns a globally unique name for this lock.
protected static function getLock($name) — Get a named lock, if it has been registered.
protected static function registerLock($lock) — Register a lock for cleanup when the process exits.

Constructing Locks

protected function __construct($name) — Build a new lock, given a lock name. The name should be globally unique across all locks.

Determining Lock Status

final public function isLocked() — Determine if the lock is currently held.

Locking

final public function lock($wait) — Acquire the lock. If lock acquisition fails because the lock is held by another process, throws @{class:PhutilLockException}. Other exceptions indicate that lock acquisition has failed for reasons unrelated to locking.
final public function unlock() — Release the lock. Throws an exception on failure, e.g. if the lock is not currently held.

Internals

public static function unlockAll() — On shutdown, we release all the locks. You should not call this method directly. Use @{method:unlock} to release individual locks.

Other Methods

public function __get($name)
public function __set($name, $value)
public function current()
public function key()
public function next()
public function rewind()
public function valid()
private function throwOnAttemptedIteration()
public function getPhobjectClassConstant($key, $byte_limit) — Read the value of a class constant.
public static function newLock($name, $parameters)
public function setExternalConnection($conn) — Use a specific database connection for locking.
public function setDisableLogging($disable)
public static function getConnectionPoolSize()
public static function clearConnectionPool()
public static function newConnection()
private function shouldLogLock()
private function newLockContext()
private function newHint($lock_name, $wait)

Methods

public function __get($name)
Inherited

This method is not documented.

Parameters

$name

Return

wild

public function __set($name, $value)
Inherited

This method is not documented.

Parameters

	$name
	$value

Return

wild

public function current()
Inherited

This method is not documented.

Return

wild

public function key()
Inherited

This method is not documented.

Return

wild

public function next()
Inherited

This method is not documented.

Return

wild

public function rewind()
Inherited

This method is not documented.

Return

wild

public function valid()
Inherited

This method is not documented.

Return

wild

private function throwOnAttemptedIteration()
Inherited

This method is not documented.

Return

wild

public function getPhobjectClassConstant($key, $byte_limit)
Inherited

Phobject

Read the value of a class constant.

This is the same as just typing self::CONSTANTNAME, but throws a more useful message if the constant is not defined and allows the constant to be limited to a maximum length.

Parameters

string	$key	Name of the constant.
int\|null	$byte_limit	Maximum number of bytes permitted in the value.

Return

string

Value of the constant.

protected function __construct($name)
Inherited

PhutilLock

Build a new lock, given a lock name. The name should be globally unique across all locks.

Parameters

string

$name

Globally unique lock name.

Return

this	//Implicit.//

protected function doLock($wait)

PhutilLock

Acquires the lock, or throws PhutilLockException if it fails.

PhabricatorGlobalLock

This method is not documented.

Parameters

float

$wait

Seconds to block waiting for the lock.

Return

void

protected function doUnlock()

PhutilLock

Releases the lock.

PhabricatorGlobalLock

This method is not documented.

Return

void

final public function getName()
Inherited

PhutilLock

Returns a globally unique name for this lock.

Return

string

Globally unique lock name, across all locks.

protected static function getLock($name)
Inherited

PhutilLock

Get a named lock, if it has been registered.

Parameters

string

$name

Lock name.

Return

wild

protected static function registerLock($lock)
Inherited

PhutilLock

Parameters

PhutilLock

$lock

Lock to register.

Return

wild

final public function isLocked()
Inherited

PhutilLock

Determine if the lock is currently held.

Return

bool	True if the lock is held.

final public function lock($wait)
Inherited

PhutilLock

Acquire the lock. If lock acquisition fails because the lock is held by another process, throws PhutilLockException. Other exceptions indicate that lock acquisition has failed for reasons unrelated to locking.

If the lock is already held by this process, this method throws. You can test the lock status with isLocked().

Parameters

float

$wait

Seconds to block waiting for the lock. By default, do not block.

Return

this

final public function unlock()
Inherited

PhutilLock

Release the lock. Throws an exception on failure, e.g. if the lock is not currently held.

Return

this

public static function unlockAll()
Inherited

PhutilLock

On shutdown, we release all the locks. You should not call this method directly. Use unlock() to release individual locks.

Return

void

public static function newLock($name, $parameters)

This method is not documented.

Parameters

	$name
	$parameters

Return

wild

public function setExternalConnection($conn)

Use a specific database connection for locking.

By default, PhabricatorGlobalLock will lock on the "repository" database (somewhat arbitrarily). In most cases this is fine, but this method can be used to lock on a specific connection.

Parameters

AphrontDatabaseConnection

$conn

Return

this

public function setDisableLogging($disable)

This method is not documented.

Parameters

$disable

Return

wild

public static function getConnectionPoolSize()

This method is not documented.

Return

wild

public static function clearConnectionPool()

This method is not documented.

Return

wild

public static function newConnection()

This method is not documented.

Return

wild

private function shouldLogLock()

This method is not documented.

Return

wild

private function newLockContext()

This method is not documented.

Return

wild

private function newHint($lock_name, $wait)

This method is not documented.

Parameters

	$lock_name
	$wait

Return

wild

Defined: src/infrastructure/util/PhabricatorGlobalLock.php:29
Extends: PhobjectPhutilLock

final class PhabricatorGlobalLockPhorge Technical Documentation ()

Tasks

Implementation

Lock Registry

Constructing Locks

Determining Lock Status

Locking

Internals

Other Methods

Methods

public function __get($name)Inherited

public function __set($name, $value)Inherited

public function current()Inherited

public function key()Inherited

public function next()Inherited

public function rewind()Inherited

public function valid()Inherited

private function throwOnAttemptedIteration()Inherited

public function getPhobjectClassConstant($key, $byte_limit)Inherited

protected function __construct($name)Inherited

protected function doLock($wait)

protected function doUnlock()

final public function getName()Inherited

protected static function getLock($name)Inherited

protected static function registerLock($lock)Inherited

final public function isLocked()Inherited

final public function lock($wait)Inherited

final public function unlock()Inherited

public static function unlockAll()Inherited

public static function newLock($name, $parameters)

public function setExternalConnection($conn)

public function setDisableLogging($disable)

public static function getConnectionPoolSize()

public static function clearConnectionPool()

public static function newConnection()

private function shouldLogLock()

private function newLockContext()

private function newHint($lock_name, $wait)

final class PhabricatorGlobalLock
Phorge Technical Documentation ()

public function __get($name)
Inherited

public function __set($name, $value)
Inherited

public function current()
Inherited

public function key()
Inherited

public function next()
Inherited

public function rewind()
Inherited

public function valid()
Inherited

private function throwOnAttemptedIteration()
Inherited

public function getPhobjectClassConstant($key, $byte_limit)
Inherited

protected function __construct($name)
Inherited

final public function getName()
Inherited

protected static function getLock($name)
Inherited

protected static function registerLock($lock)
Inherited

final public function isLocked()
Inherited

final public function lock($wait)
Inherited

final public function unlock()
Inherited

public static function unlockAll()
Inherited