MediaWiki  master
LockManager Class Reference

Class for handling resource locking. More...

Inheritance diagram for LockManager:
Collaboration diagram for LockManager:

Public Member Functions

 __construct (array $config)
 Construct a new instance from configuration. More...
 
 lock (array $paths, $type=self::LOCK_EX, $timeout=0)
 Lock the resources at the given abstract paths. More...
 
 lockByType (array $pathsByType, $timeout=0)
 Lock the resources at the given abstract paths. More...
 
 unlock (array $paths, $type=self::LOCK_EX)
 Unlock the resources at the given abstract paths. More...
 
 unlockByType (array $pathsByType)
 Unlock the resources at the given abstract paths. More...
 

Public Attributes

const LOCK_EX = 3
 
const LOCK_SH = 1
 Lock types; stronger locks have higher values. More...
 
const LOCK_UW = 2
 

Protected Member Functions

 doLock (array $paths, $type)
 Lock resources with the given keys and lock type. More...
 
 doLockByType (array $pathsByType)
 
 doUnlock (array $paths, $type)
 Unlock resources with the given keys and lock type. More...
 
 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. More...
 
 sha1Base16Absolute ( $path)
 Get the base 16 SHA-1 of a string, padded to 31 digits. More...
 
 sha1Base36Absolute ( $path)
 Get the base 36 SHA-1 of a string, padded to 31 digits. More...
 

Protected Attributes

 $domain
 
array $locksHeld = []
 Map of (resource path => lock type => count) More...
 
 $lockTTL
 
array $lockTypeMap
 Mapping of lock types to the type actually used. More...
 
LoggerInterface $logger
 
string $session
 Random 32-char hex number. More...
 
const CLI_LOCK_TTL = 3600
 Default lock TTL in CLI mode. More...
 
const MAX_LOCK_TTL = 2 * 3600
 Max expected lock expiry in any context. More...
 
const MIN_GUESSED_LOCK_TTL = 5 * 60
 The minimum lock TTL if it is guessed from max_execution_time rather than configured. More...
 
const MIN_LOCK_TTL = 5
 Minimum lock TTL. More...
 

Detailed Description

Class for handling resource locking.

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 49 of file LockManager.php.

Constructor & Destructor Documentation

◆ __construct()

LockManager::__construct ( array  $config)

Construct a new instance from configuration.

Stability: stable
to call
Parameters
array$configParameters include:
  • domain : Domain (usually wiki ID) that all resources are relative to [optional]
  • lockTTL : Age (in seconds) at which resource locks should expire. This only applies if locks are not tied to a connection/process.

Reimplemented in RedisLockManager, MemcLockManager, FSLockManager, DBLockManager, and MySqlLockManager.

Definition at line 95 of file LockManager.php.

References CLI_LOCK_TTL, and MIN_GUESSED_LOCK_TTL.

Member Function Documentation

◆ doLock()

LockManager::doLock ( array  $paths,
  $type 
)
abstractprotected

Lock resources with the given keys and lock type.

Parameters
array$pathsList of paths
int$typeLockManager::LOCK_* constant
Returns
StatusValue

Reimplemented in QuorumLockManager, NullLockManager, and FSLockManager.

Referenced by doLockByType().

◆ doLockByType()

LockManager::doLockByType ( array  $pathsByType)
protected
See also
LockManager::lockByType()
Stability: stable
to override
Parameters
array$pathsByTypeMap of LockManager::LOCK_* constants to lists of paths
Returns
StatusValue
Since
1.22

Reimplemented in QuorumLockManager.

Definition at line 237 of file LockManager.php.

References $type, doLock(), doUnlock(), and StatusValue\newGood().

Referenced by lockByType().

◆ doUnlock()

LockManager::doUnlock ( array  $paths,
  $type 
)
abstractprotected

Unlock resources with the given keys and lock type.

Parameters
array$pathsList of paths
int$typeLockManager::LOCK_* constant
Returns
StatusValue

Reimplemented in QuorumLockManager, NullLockManager, and FSLockManager.

Referenced by doLockByType(), and doUnlockByType().

◆ doUnlockByType()

LockManager::doUnlockByType ( array  $pathsByType)
protected
See also
LockManager::unlockByType()
Stability: stable
to override
Parameters
array$pathsByTypeMap of LockManager::LOCK_* constants to lists of paths
Returns
StatusValue
Since
1.22

Reimplemented in QuorumLockManager.

Definition at line 272 of file LockManager.php.

References $type, doUnlock(), and StatusValue\newGood().

Referenced by unlockByType().

◆ lock()

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

Lock the resources at the given abstract paths.

Parameters
array$pathsList of resource names
int$typeLockManager::LOCK_* constant
int$timeoutTimeout in seconds (0 means non-blocking) (since 1.21)
Returns
StatusValue

Definition at line 129 of file LockManager.php.

References $type, and lockByType().

Referenced by RedisLockManager\getLocksOnServer().

◆ lockByType()

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

Lock the resources at the given abstract paths.

Parameters
array$pathsByTypeMap of LockManager::LOCK_* constants to lists of paths
int$timeoutTimeout in seconds (0 means non-blocking) (since 1.21)
Returns
StatusValue
Since
1.22

Definition at line 141 of file LockManager.php.

References doLockByType(), and normalizePathsByType().

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

◆ normalizePathsByType()

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$pathsByTypeMap of LockManager::LOCK_* constants to lists of paths
Returns
array
Since
1.22

Definition at line 216 of file LockManager.php.

References $path, $res, and $type.

Referenced by lockByType(), and unlockByType().

◆ sha1Base16Absolute()

LockManager::sha1Base16Absolute (   $path)
finalprotected

Get the base 16 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 204 of file LockManager.php.

◆ sha1Base36Absolute()

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 192 of file LockManager.php.

Referenced by MySqlLockManager\doGetLocksOnServer(), MemcLockManager\recordKeyForPath(), and RedisLockManager\recordKeyForPath().

◆ unlock()

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

Unlock the resources at the given abstract paths.

Parameters
array$pathsList of paths
int$typeLockManager::LOCK_* constant
Returns
StatusValue

Definition at line 166 of file LockManager.php.

References $type, and unlockByType().

◆ unlockByType()

LockManager::unlockByType ( array  $pathsByType)
final

Unlock the resources at the given abstract paths.

Parameters
array$pathsByTypeMap of LockManager::LOCK_* constants to lists of paths
Returns
StatusValue
Since
1.22

Definition at line 177 of file LockManager.php.

References doUnlockByType(), and normalizePathsByType().

Referenced by RedisLockManager\__destruct(), and unlock().

Member Data Documentation

◆ $domain

LockManager::$domain
protected

Definition at line 63 of file LockManager.php.

◆ $locksHeld

array LockManager::$locksHeld = []
protected

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

Definition at line 61 of file LockManager.php.

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

◆ $lockTTL

LockManager::$lockTTL
protected

Definition at line 64 of file LockManager.php.

Referenced by MemcLockManager\getLocksOnServer().

◆ $lockTypeMap

array LockManager::$lockTypeMap
protected
Initial value:
= [
self::LOCK_SH => self::LOCK_SH,
self::LOCK_UW => self::LOCK_EX,
self::LOCK_EX => self::LOCK_EX
]
const LOCK_SH
Lock types; stronger locks have higher values.
Definition: LockManager.php:70
const LOCK_EX
Definition: LockManager.php:72

Mapping of lock types to the type actually used.

Definition at line 54 of file LockManager.php.

◆ $logger

LoggerInterface LockManager::$logger
protected

Definition at line 51 of file LockManager.php.

◆ $session

string LockManager::$session
protected

Random 32-char hex number.

Definition at line 67 of file LockManager.php.

Referenced by MySqlLockManager\doGetLocksOnServer(), and MemcLockManager\getLocksOnServer().

◆ CLI_LOCK_TTL

const LockManager::CLI_LOCK_TTL = 3600
protected

Default lock TTL in CLI mode.

Definition at line 78 of file LockManager.php.

Referenced by __construct().

◆ LOCK_EX

◆ LOCK_SH

const LockManager::LOCK_SH = 1

◆ LOCK_UW

◆ MAX_LOCK_TTL

const LockManager::MAX_LOCK_TTL = 2 * 3600
protected

Max expected lock expiry in any context.

Definition at line 75 of file LockManager.php.

◆ MIN_GUESSED_LOCK_TTL

const LockManager::MIN_GUESSED_LOCK_TTL = 5 * 60
protected

The minimum lock TTL if it is guessed from max_execution_time rather than configured.

Definition at line 84 of file LockManager.php.

Referenced by __construct().

◆ MIN_LOCK_TTL

const LockManager::MIN_LOCK_TTL = 5
protected

Minimum lock TTL.

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

Definition at line 81 of file LockManager.php.


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