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  // @phan-suppress-next-line PhanTypeMismatchReturn WaitConditionLoop throws or status is set
156  return $status;
157  }
158 
166  final public function unlock( array $paths, $type = self::LOCK_EX ) {
167  return $this->unlockByType( [ $type => $paths ] );
168  }
169 
177  final public function unlockByType( array $pathsByType ) {
178  $pathsByType = $this->normalizePathsByType( $pathsByType );
179  $status = $this->doUnlockByType( $pathsByType );
180 
181  return $status;
182  }
183 
192  final protected function sha1Base36Absolute( $path ) {
193  return Wikimedia\base_convert( sha1( "{$this->domain}:{$path}" ), 16, 36, 31 );
194  }
195 
204  final protected function sha1Base16Absolute( $path ) {
205  return sha1( "{$this->domain}:{$path}" );
206  }
207 
216  final protected function normalizePathsByType( array $pathsByType ) {
217  $res = [];
218  foreach ( $pathsByType as $type => $paths ) {
219  foreach ( $paths as $path ) {
220  if ( (string)$path === '' ) {
221  throw new InvalidArgumentException( __METHOD__ . ": got empty path." );
222  }
223  }
224  $res[$this->lockTypeMap[$type]] = array_unique( $paths );
225  }
226 
227  return $res;
228  }
229 
237  protected function doLockByType( array $pathsByType ) {
238  $status = StatusValue::newGood();
239  $lockedByType = []; // map of (type => paths)
240  foreach ( $pathsByType as $type => $paths ) {
241  $status->merge( $this->doLock( $paths, $type ) );
242  if ( $status->isOK() ) {
243  $lockedByType[$type] = $paths;
244  } else {
245  // Release the subset of locks that were acquired
246  foreach ( $lockedByType as $lType => $lPaths ) {
247  $status->merge( $this->doUnlock( $lPaths, $lType ) );
248  }
249  break;
250  }
251  }
252 
253  return $status;
254  }
255 
263  abstract protected function doLock( array $paths, $type );
264 
272  protected function doUnlockByType( array $pathsByType ) {
273  $status = StatusValue::newGood();
274  foreach ( $pathsByType as $type => $paths ) {
275  $status->merge( $this->doUnlock( $paths, $type ) );
276  }
277 
278  return $status;
279  }
280 
288  abstract protected function doUnlock( array $paths, $type );
289 }
Class for handling resource locking.
Definition: LockManager.php:49
const CLI_LOCK_TTL
Default lock TTL in CLI mode.
Definition: LockManager.php:78
doUnlockByType(array $pathsByType)
const MIN_LOCK_TTL
Minimum lock TTL.
Definition: LockManager.php:81
array $lockTypeMap
Mapping of lock types to the type actually used.
Definition: LockManager.php:54
lock(array $paths, $type=self::LOCK_EX, $timeout=0)
Lock the resources at the given abstract paths.
const MIN_GUESSED_LOCK_TTL
The minimum lock TTL if it is guessed from max_execution_time rather than configured.
Definition: LockManager.php:84
doUnlock(array $paths, $type)
Unlock resources with the given keys and lock type.
doLock(array $paths, $type)
Lock resources with the given keys and lock type.
string $session
Random 32-char hex number.
Definition: LockManager.php:67
lockByType(array $pathsByType, $timeout=0)
Lock the resources at the given abstract paths.
const LOCK_SH
Lock types; stronger locks have higher values.
Definition: LockManager.php:70
doLockByType(array $pathsByType)
normalizePathsByType(array $pathsByType)
Normalize the $paths array by converting LOCK_UW locks into the appropriate type and removing any dup...
LoggerInterface $logger
Definition: LockManager.php:51
const MAX_LOCK_TTL
Max expected lock expiry in any context.
Definition: LockManager.php:75
const LOCK_EX
Definition: LockManager.php:72
sha1Base36Absolute( $path)
Get the base 36 SHA-1 of a string, padded to 31 digits.
const LOCK_UW
Definition: LockManager.php:71
unlock(array $paths, $type=self::LOCK_EX)
Unlock the resources at the given abstract paths.
array $locksHeld
Map of (resource path => lock type => count)
Definition: LockManager.php:61
sha1Base16Absolute( $path)
Get the base 16 SHA-1 of a string, padded to 31 digits.
unlockByType(array $pathsByType)
Unlock the resources at the given abstract paths.
__construct(array $config)
Construct a new instance from configuration.
Definition: LockManager.php:95
static newGood( $value=null)
Factory function for good results.
Definition: StatusValue.php:82