Page MenuHomePhabricator

final class PhutilFileLock
libphutil Technical Documentation (Filesystem)

Wrapper around flock() for advisory filesystem locking. Usage is straightforward:

$path = '/path/to/lock.file';
$lock = PhutilFileLock::newForPath($path);
$lock->lock();

  do_contentious_things();

$lock->unlock();

For more information on locks, see PhutilLock.

Tasks

Implementation

No methods for this task.

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.
  • public static function newForPath($lockfile) — Create a new lock on a lockfile. The file need not exist yet.

Determining Lock Status

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

Locking

  • protected function doLock($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.
  • protected function doUnlock() — Release the lock. Throws an exception on failure, e.g. if the lock is not currently held.
  • 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)
Inherited

PhutilLock

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

protected function doLock($wait)

PhutilLock

Acquires the lock, or throws PhutilLockException if it fails.

PhutilFileLock

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, this method throws. You can test the lock status with isLocked().

Parameters
float$waitSeconds to block waiting for the lock.
Return
void

protected function doUnlock()

PhutilLock

Releases the lock.

PhutilFileLock

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

Return
void

final public function getName()
Inherited

PhutilLock

Returns a globally unique name for this lock.

Return
stringGlobally unique lock name, across all locks.

protected static function getLock($name)
Inherited

PhutilLock

Get a named lock, if it has been registered.

Parameters
string$nameLock name.
Return
wild

protected static function registerLock($lock)
Inherited

PhutilLock

Register a lock for cleanup when the process exits.

Parameters
PhutilLock$lockLock to register.
Return
wild

final public function isLocked()
Inherited

PhutilLock

Determine if the lock is currently held.

Return
boolTrue 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$waitSeconds 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 newForPath($lockfile)

Create a new lock on a lockfile. The file need not exist yet.

Parameters
string$lockfileThe lockfile to use.
Return
PhutilFileLockNew lock object.