Diviner libphutil Tech Docs PhutilLock

abstract class PhutilLock
libphutil Technical Documentation (Filesystem)

Base class for locks, like file locks.

libphutil provides a concrete lock in PhutilFileLock.

$lock->lock();
  do_contentious_things();
$lock->unlock();

If the lock can't be acquired because it is already held, PhutilLockException is thrown. Other exceptions indicate permanent failure unrelated to locking.

When extending this class, you should call getLock() to look up an existing lock object, and registerLock() when objects are constructed to register for automatic unlock on shutdown.

Tasks

Lock Implementation

abstract protected function doLock($wait) — Acquires the lock, or throws @{class:PhutilLockException} if it fails.
abstract protected function doUnlock() — Releases the lock.

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.

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)

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.//

abstract protected function doLock($wait)

Acquires the lock, or throws PhutilLockException if it fails.

Parameters

float

$wait

Seconds to block waiting for the lock.

Return

void

abstract protected function doUnlock()

Releases the lock.

Return

void

final public function getName()

Returns a globally unique name for this lock.

Return

string

Globally unique lock name, across all locks.

protected static function getLock($name)

Get a named lock, if it has been registered.

Parameters

string

$name

Lock name.

Return

wild

protected static function registerLock($lock)

Register a lock for cleanup when the process exits.

Parameters

PhutilLock

$lock

Lock to register.

Return

wild

final public function isLocked()

Determine if the lock is currently held.

Return

bool	True if the lock is held.

final public function lock($wait)

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()

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

Return

this

public static function unlockAll()

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

Return

void

Defined: src/filesystem/PhutilLock.php:28
Extends: Phobject