Page MenuHomePhabricator
Diviner Arcanist Tech Docs PhutilLock

abstract class PhutilLock
Arcanist Technical Documentation ()

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.

Methods

protected function __construct($name)

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

Parameters
string$nameGlobally unique lock name.
Return
this//Implicit.//

abstract protected function doLock($wait)

Acquires the lock, or throws PhutilLockException if it fails.

Parameters
float$waitSeconds 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
stringGlobally unique lock name, across all locks.

protected static function getLock($name)

Get a named lock, if it has been registered.

Parameters
string$nameLock name.
Return
wild

protected static function registerLock($lock)

Register a lock for cleanup when the process exits.

Parameters
PhutilLock$lockLock to register.
Return
wild

final public function isLocked()

Determine if the lock is currently held.

Return
boolTrue 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$waitSeconds 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
Phabricator · Built by Phacility