MediaWiki  master
LockManager.php
Go to the documentation of this file.
1 <?php
6 use Psr\Log\LoggerInterface;
7 use Psr\Log\NullLogger;
8 use Wikimedia\RequestTimeout\RequestTimeout;
9 use Wikimedia\WaitConditionLoop;
10 
49 abstract class LockManager {
51  protected $logger;
52 
54  protected $lockTypeMap = [
55  self::LOCK_SH => self::LOCK_SH,
56  self::LOCK_UW => self::LOCK_EX, // subclasses may use self::LOCK_SH
57  self::LOCK_EX => self::LOCK_EX
58  ];
59 
61  protected $locksHeld = [];
62 
63  protected $domain; // string; domain (usually wiki ID)
64  protected $lockTTL; // integer; maximum time locks can be held
65 
67  protected $session;
68 
70  public const LOCK_SH = 1; // shared lock (for reads)
71  public const LOCK_UW = 2; // shared lock (for reads used to write elsewhere)
72  public const LOCK_EX = 3; // exclusive lock (for writes)
73 
75  protected const MAX_LOCK_TTL = 2 * 3600; // 2 hours
76 
78  protected const CLI_LOCK_TTL = 3600; // 1 hour
79 
81  protected const MIN_LOCK_TTL = 5; // seconds
82 
84  protected const MIN_GUESSED_LOCK_TTL = 5 * 60; // 5 minutes
85 
95  public function __construct( array $config ) {
96  $this->domain = $config['domain'] ?? 'global';
97  if ( isset( $config['lockTTL'] ) ) {
98  $this->lockTTL = max( self::MIN_LOCK_TTL, $config['lockTTL'] );
99  } elseif ( PHP_SAPI === 'cli' || PHP_SAPI === 'phpdbg' ) {
100  $this->lockTTL = self::CLI_LOCK_TTL;
101  } else {
102  $ttl = 2 * ceil( RequestTimeout::singleton()->getWallTimeLimit() );
103  $this->lockTTL = ( $ttl === INF || $ttl < self::MIN_GUESSED_LOCK_TTL )
104  ? self::MIN_GUESSED_LOCK_TTL : $ttl;
105  }
106 
107  // Upper bound on how long to keep lock structures around. This is useful when setting
108  // TTLs, as the "lockTTL" value may vary based on CLI mode and app server group. This is
109  // a "safe" value that can be used to avoid clobbering other locks that use high TTLs.
110  $this->lockTTL = min( $this->lockTTL, self::MAX_LOCK_TTL );
111 
112  $random = [];
113  for ( $i = 1; $i <= 5; ++$i ) {
114  $random[] = mt_rand( 0, 0xFFFFFFF );
115  }
116  $this->session = md5( implode( '-', $random ) );
117 
118  $this->logger = $config['logger'] ?? new NullLogger();
119  }
120 
129  final public function lock( array $paths, $type = self::LOCK_EX, $timeout = 0 ) {
130  return $this->lockByType( [ $type => $paths ], $timeout );
131  }
132 
141  final public function lockByType( array $pathsByType, $timeout = 0 ) {
142  $pathsByType = $this->normalizePathsByType( $pathsByType );
143 
144  $status = null;
145  $loop = new WaitConditionLoop(
146  function () use ( &$status, $pathsByType ) {
147  $status = $this->doLockByType( $pathsByType );
148 
149  return $status->isOK() ?: WaitConditionLoop::CONDITION_CONTINUE;
150  },
151  $timeout
152  );
153  $loop->invoke();
154 
155  return $status;
156  }
157 
165  final public function unlock( array $paths, $type = self::LOCK_EX ) {
166  return $this->unlockByType( [ $type => $paths ] );
167  }
168 
176  final public function unlockByType( array $pathsByType ) {
177  $pathsByType = $this->normalizePathsByType( $pathsByType );
178  $status = $this->doUnlockByType( $pathsByType );
179 
180  return $status;
181  }
182 
191  final protected function sha1Base36Absolute( $path ) {
192  return Wikimedia\base_convert( sha1( "{$this->domain}:{$path}" ), 16, 36, 31 );
193  }
194 
203  final protected function sha1Base16Absolute( $path ) {
204  return sha1( "{$this->domain}:{$path}" );
205  }
206 
215  final protected function normalizePathsByType( array $pathsByType ) {
216  $res = [];
217  foreach ( $pathsByType as $type => $paths ) {
218  foreach ( $paths as $path ) {
219  if ( (string)$path === '' ) {
220  throw new InvalidArgumentException( __METHOD__ . ": got empty path." );
221  }
222  }
223  $res[$this->lockTypeMap[$type]] = array_unique( $paths );
224  }
225 
226  return $res;
227  }
228 
236  protected function doLockByType( array $pathsByType ) {
237  $status = StatusValue::newGood();
238  $lockedByType = []; // map of (type => paths)
239  foreach ( $pathsByType as $type => $paths ) {
240  $status->merge( $this->doLock( $paths, $type ) );
241  if ( $status->isOK() ) {
242  $lockedByType[$type] = $paths;
243  } else {
244  // Release the subset of locks that were acquired
245  foreach ( $lockedByType as $lType => $lPaths ) {
246  $status->merge( $this->doUnlock( $lPaths, $lType ) );
247  }
248  break;
249  }
250  }
251 
252  return $status;
253  }
254 
262  abstract protected function doLock( array $paths, $type );
263 
271  protected function doUnlockByType( array $pathsByType ) {
272  $status = StatusValue::newGood();
273  foreach ( $pathsByType as $type => $paths ) {
274  $status->merge( $this->doUnlock( $paths, $type ) );
275  }
276 
277  return $status;
278  }
279 
287  abstract protected function doUnlock( array $paths, $type );
288 }
LockManager
Class for handling resource locking.
Definition: LockManager.php:49
LockManager\$locksHeld
array $locksHeld
Map of (resource path => lock type => count)
Definition: LockManager.php:61
LockManager\LOCK_SH
const LOCK_SH
Lock types; stronger locks have higher values.
Definition: LockManager.php:70
LockManager\sha1Base16Absolute
sha1Base16Absolute( $path)
Get the base 16 SHA-1 of a string, padded to 31 digits.
Definition: LockManager.php:203
LockManager\LOCK_UW
const LOCK_UW
Definition: LockManager.php:71
$res
$res
Definition: testCompression.php:57
LockManager\$lockTypeMap
array $lockTypeMap
Mapping of lock types to the type actually used.
Definition: LockManager.php:54
LockManager\MAX_LOCK_TTL
const MAX_LOCK_TTL
Max expected lock expiry in any context.
Definition: LockManager.php:75
LockManager\normalizePathsByType
normalizePathsByType(array $pathsByType)
Normalize the $paths array by converting LOCK_UW locks into the appropriate type and removing any dup...
Definition: LockManager.php:215
LockManager\$lockTTL
$lockTTL
Definition: LockManager.php:64
LockManager\sha1Base36Absolute
sha1Base36Absolute( $path)
Get the base 36 SHA-1 of a string, padded to 31 digits.
Definition: LockManager.php:191
LockManager\doUnlockByType
doUnlockByType(array $pathsByType)
Definition: LockManager.php:271
LockManager\unlock
unlock(array $paths, $type=self::LOCK_EX)
Unlock the resources at the given abstract paths.
Definition: LockManager.php:165
LockManager\lock
lock(array $paths, $type=self::LOCK_EX, $timeout=0)
Lock the resources at the given abstract paths.
Definition: LockManager.php:129
LockManager\MIN_LOCK_TTL
const MIN_LOCK_TTL
Minimum lock TTL.
Definition: LockManager.php:81
LockManager\unlockByType
unlockByType(array $pathsByType)
Unlock the resources at the given abstract paths.
Definition: LockManager.php:176
StatusValue\newGood
static newGood( $value=null)
Factory function for good results.
Definition: StatusValue.php:82
LockManager\$logger
LoggerInterface $logger
Definition: LockManager.php:51
LockManager\$session
string $session
Random 32-char hex number.
Definition: LockManager.php:67
LockManager\doUnlock
doUnlock(array $paths, $type)
Unlock resources with the given keys and lock type.
$path
$path
Definition: NoLocalSettings.php:25
LockManager\MIN_GUESSED_LOCK_TTL
const MIN_GUESSED_LOCK_TTL
The minimum lock TTL if it is guessed from max_execution_time rather than configured.
Definition: LockManager.php:84
LockManager\__construct
__construct(array $config)
Construct a new instance from configuration.
Definition: LockManager.php:95
LockManager\LOCK_EX
const LOCK_EX
Definition: LockManager.php:72
LockManager\doLock
doLock(array $paths, $type)
Lock resources with the given keys and lock type.
LockManager\CLI_LOCK_TTL
const CLI_LOCK_TTL
Default lock TTL in CLI mode.
Definition: LockManager.php:78
LockManager\doLockByType
doLockByType(array $pathsByType)
Definition: LockManager.php:236
LockManager\lockByType
lockByType(array $pathsByType, $timeout=0)
Lock the resources at the given abstract paths.
Definition: LockManager.php:141
LockManager\$domain
$domain
Definition: LockManager.php:63
$type
$type
Definition: testCompression.php:52