Resource locking handling. More...

Inherited by Wikimedia\LockManager\FSLockManager, Wikimedia\LockManager\NullLockManager, and Wikimedia\LockManager\QuorumLockManager.

Collaboration diagram for Wikimedia\LockManager\LockManager:

[legend]

Public Member Functions
	__construct (array $config)
	Construct a new instance from configuration.

	lock (array $paths, $type=self::LOCK_EX, $timeout=0)
	Lock the resources at the given abstract paths.

	lockByType (array $pathsByType, $timeout=0)
	Lock the resources at the given abstract paths.

	unlock (array $paths, $type=self::LOCK_EX)
	Unlock the resources at the given abstract paths.

	unlockByType (array $pathsByType)
	Unlock the resources at the given abstract paths.

Public Attributes
const	LOCK_EX = 3

const	LOCK_SH = 1
	Lock types; stronger locks have higher values.

const	LOCK_UW = 2

Protected Member Functions
	doLock (array $paths, $type)
	Lock resources with the given keys and lock type.

	doLockByType (array $pathsByType)

	doUnlock (array $paths, $type)
	Unlock resources with the given keys and lock type.

	doUnlockByType (array $pathsByType)

	normalizePathsByType (array $pathsByType)
	Normalize the $paths array by converting LOCK_UW locks into the appropriate type and removing any duplicated paths for each lock type.

	sha1Base36Absolute ( $path)
	Get the base 36 SHA-1 of a string, padded to 31 digits.

Protected Attributes
string	$domain
	domain (usually wiki ID)

array	$locksHeld = []
	Map of (resource path => lock type => count)

int	$lockTTL
	maximum time locks can be held

array	$lockTypeMap
	Mapping of lock types to the type actually used.

LoggerInterface	$logger

string	$session
	Random 32-char hex number.

const	MAX_LOCK_TTL = 2 * 3600
	Max expected lock expiry in any context.

const	MIN_LOCK_TTL = 5
	Minimum lock TTL.

Detailed Description

Resource locking handling.

Locks on resource keys can either be shared or exclusive.

Implementations must keep track of what is locked by this process in-memory and support nested locking calls (using reference counting). At least LOCK_UW and LOCK_EX must be implemented. LOCK_SH can be a no-op. Locks should either be non-blocking or have low wait timeouts.

Subclasses should avoid throwing exceptions at all costs.

Stability: stable: to extend

Since: 1.19

Definition at line 36 of file LockManager.php.

Constructor & Destructor Documentation

◆ __construct()

Wikimedia\LockManager\LockManager::__construct ( array $config )

Construct a new instance from configuration.

Stability: stable: to call

Parameters

array

$config

Parameters include:

domain : [optional] Domain (usually wiki ID) that all resources are relative to.
lockTTL : [optional] Customize the maximum duration (in seconds) that a lock may be held for. This TTL is stored by LockManager subclasses and serves as a recovery mechanism. If a process crashes before it can unlock, locks are eventually released. Default for web: 5min, or twice the length of max_execution_time (if higher). Default for CLI: 1 hour.

Reimplemented in Wikimedia\LockManager\FSLockManager, Wikimedia\LockManager\MemcLockManager, and Wikimedia\LockManager\RedisLockManager.

Definition at line 82 of file LockManager.php.

Member Function Documentation

◆ doLock()

Wikimedia\LockManager\LockManager::doLock	(	array	$paths,
			$type )

abstractprotected

Lock resources with the given keys and lock type.

Parameters

array	$paths	List of paths
int	$type	LockManager::LOCK_* constant

Returns: StatusValue

Reimplemented in Wikimedia\LockManager\FSLockManager, Wikimedia\LockManager\NullLockManager, and Wikimedia\LockManager\QuorumLockManager.

Referenced by Wikimedia\LockManager\LockManager\doLockByType().

◆ doLockByType()

Wikimedia\LockManager\LockManager::doLockByType ( array $pathsByType )

protected

See also: LockManager::lockByType()

Stability: stable: to override

Parameters

array $pathsByType Map of LockManager::LOCK_* constants to lists of paths

Returns: StatusValue

Since: 1.22

Reimplemented in Wikimedia\LockManager\QuorumLockManager.

Definition at line 209 of file LockManager.php.

References Wikimedia\LockManager\LockManager\doLock(), and Wikimedia\LockManager\LockManager\doUnlock().

Referenced by Wikimedia\LockManager\LockManager\lockByType().

◆ doUnlock()

Wikimedia\LockManager\LockManager::doUnlock	(	array	$paths,
			$type )

abstractprotected

Unlock resources with the given keys and lock type.

Parameters

array	$paths	List of paths
int	$type	LockManager::LOCK_* constant

Returns: StatusValue

Reimplemented in Wikimedia\LockManager\FSLockManager, Wikimedia\LockManager\NullLockManager, and Wikimedia\LockManager\QuorumLockManager.

Referenced by Wikimedia\LockManager\LockManager\doLockByType(), and Wikimedia\LockManager\LockManager\doUnlockByType().

◆ doUnlockByType()

Wikimedia\LockManager\LockManager::doUnlockByType ( array $pathsByType )

protected

See also: LockManager::unlockByType()

Stability: stable: to override

Parameters

array $pathsByType Map of LockManager::LOCK_* constants to lists of paths

Returns: StatusValue

Since: 1.22

Reimplemented in Wikimedia\LockManager\QuorumLockManager.

Definition at line 244 of file LockManager.php.

References Wikimedia\LockManager\LockManager\doUnlock().

Referenced by Wikimedia\LockManager\LockManager\unlockByType().

◆ lock()

Wikimedia\LockManager\LockManager::lock	(	array	$paths,
			$type = self::LOCK_EX,
			$timeout = 0 )

final

Lock the resources at the given abstract paths.

Parameters

array	$paths	List of resource names
int	$type	LockManager::LOCK_* constant
int	$timeout	Timeout in seconds (0 means non-blocking) (since 1.21)

Returns: StatusValue

Definition at line 113 of file LockManager.php.

References Wikimedia\LockManager\LockManager\lockByType().

Referenced by Wikimedia\LockManager\RedisLockManager\getLocksOnServer().

◆ lockByType()

Wikimedia\LockManager\LockManager::lockByType	(	array	$pathsByType,
			$timeout = 0 )

final

Lock the resources at the given abstract paths.

Parameters

array	$pathsByType	Map of LockManager::LOCK_* constants to lists of paths
int	$timeout	Timeout in seconds (0 means non-blocking) (since 1.21)

Returns: StatusValue

Since: 1.22

Definition at line 125 of file LockManager.php.

References Wikimedia\LockManager\LockManager\doLockByType(), and Wikimedia\LockManager\LockManager\normalizePathsByType().

Referenced by Wikimedia\LockManager\ScopedLock\factory(), and Wikimedia\LockManager\LockManager\lock().

◆ normalizePathsByType()

Wikimedia\LockManager\LockManager::normalizePathsByType ( array $pathsByType )

finalprotected

Normalize the $paths array by converting LOCK_UW locks into the appropriate type and removing any duplicated paths for each lock type.

Parameters

array $pathsByType Map of LockManager::LOCK_* constants to lists of paths

Returns: array

Since: 1.22

Definition at line 188 of file LockManager.php.

References $path.

Referenced by Wikimedia\LockManager\LockManager\lockByType(), and Wikimedia\LockManager\LockManager\unlockByType().

◆ sha1Base36Absolute()

Wikimedia\LockManager\LockManager::sha1Base36Absolute ( $path )

finalprotected

Get the base 36 SHA-1 of a string, padded to 31 digits.

Before hashing, the path will be prefixed with the domain ID. This should be used internally for lock key or file names.

Parameters

string $path

Returns: string

Definition at line 176 of file LockManager.php.

Referenced by Wikimedia\LockManager\MemcLockManager\recordKeyForPath(), and Wikimedia\LockManager\RedisLockManager\recordKeyForPath().

◆ unlock()

Wikimedia\LockManager\LockManager::unlock	(	array	$paths,
			$type = self::LOCK_EX )

final

Unlock the resources at the given abstract paths.

Parameters

array	$paths	List of paths
int	$type	LockManager::LOCK_* constant

Returns: StatusValue

Definition at line 150 of file LockManager.php.

References Wikimedia\LockManager\LockManager\unlockByType().

◆ unlockByType()

Wikimedia\LockManager\LockManager::unlockByType ( array $pathsByType )

final

Unlock the resources at the given abstract paths.

Parameters

array $pathsByType Map of LockManager::LOCK_* constants to lists of paths

Returns: StatusValue

Since: 1.22

Definition at line 161 of file LockManager.php.

References Wikimedia\LockManager\LockManager\doUnlockByType(), and Wikimedia\LockManager\LockManager\normalizePathsByType().

Referenced by Wikimedia\LockManager\MemcLockManager\__destruct(), Wikimedia\LockManager\RedisLockManager\__destruct(), and Wikimedia\LockManager\LockManager\unlock().

Member Data Documentation

◆ $domain

string Wikimedia\LockManager\LockManager::$domain

protected

domain (usually wiki ID)

Definition at line 51 of file LockManager.php.

◆ $locksHeld

array Wikimedia\LockManager\LockManager::$locksHeld = []

protected

Map of (resource path => lock type => count)

Definition at line 48 of file LockManager.php.

Referenced by Wikimedia\LockManager\MemcLockManager\freeLocksOnServer(), and Wikimedia\LockManager\MemcLockManager\getLocksOnServer().

◆ $lockTTL

int Wikimedia\LockManager\LockManager::$lockTTL

protected

maximum time locks can be held

Definition at line 53 of file LockManager.php.

Referenced by Wikimedia\LockManager\MemcLockManager\getLocksOnServer().

◆ $lockTypeMap

array Wikimedia\LockManager\LockManager::$lockTypeMap

protected

Initial value:

= [
        self::LOCK_SH => self::LOCK_SH,
        self::LOCK_UW => self::LOCK_EX, 
        self::LOCK_EX => self::LOCK_EX
    ]

Mapping of lock types to the type actually used.

Definition at line 41 of file LockManager.php.

◆ $logger

LoggerInterface Wikimedia\LockManager\LockManager::$logger

protected

Definition at line 38 of file LockManager.php.

◆ $session

string Wikimedia\LockManager\LockManager::$session

protected

Random 32-char hex number.

Definition at line 56 of file LockManager.php.

Referenced by Wikimedia\LockManager\MemcLockManager\getLocksOnServer().

◆ LOCK_EX

const Wikimedia\LockManager\LockManager::LOCK_EX = 3

Definition at line 61 of file LockManager.php.

Referenced by Wikimedia\LockManager\FSLockManager\doSingleLock().

◆ LOCK_SH

const Wikimedia\LockManager\LockManager::LOCK_SH = 1

Lock types; stronger locks have higher values.

Definition at line 59 of file LockManager.php.

Referenced by Wikimedia\LockManager\FSLockManager\doSingleLock(), Wikimedia\LockManager\RedisLockManager\freeLocksOnServer(), and Wikimedia\LockManager\RedisLockManager\getLocksOnServer().

◆ LOCK_UW

const Wikimedia\LockManager\LockManager::LOCK_UW = 2

Definition at line 60 of file LockManager.php.

◆ MAX_LOCK_TTL

const Wikimedia\LockManager\LockManager::MAX_LOCK_TTL = 2 * 3600

protected

Max expected lock expiry in any context.

Definition at line 64 of file LockManager.php.

◆ MIN_LOCK_TTL

const Wikimedia\LockManager\LockManager::MIN_LOCK_TTL = 5

protected

Minimum lock TTL.

The configured lockTTL is ignored if it is less than this value.

Definition at line 67 of file LockManager.php.

The documentation for this class was generated from the following file:

includes/libs/LockManager/LockManager.php

Public Member Functions

Public Attributes

Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ __construct()

Member Function Documentation

◆ doLock()

◆ doLockByType()

◆ doUnlock()

◆ doUnlockByType()

◆ lock()

◆ lockByType()

◆ normalizePathsByType()

◆ sha1Base36Absolute()

◆ unlock()

◆ unlockByType()

Member Data Documentation

◆ $domain

◆ $locksHeld

◆ $lockTTL

◆ $lockTypeMap

◆ $logger

◆ $session

◆ LOCK_EX

◆ LOCK_SH

◆ LOCK_UW

◆ MAX_LOCK_TTL

◆ MIN_LOCK_TTL