MediaWiki  master
LockManager.php
Go to the documentation of this file.
1 <?php
21 use Psr\Log\LoggerInterface;
22 use Psr\Log\NullLogger;
23 use Wikimedia\RequestTimeout\RequestTimeout;
24 use Wikimedia\WaitConditionLoop;
25 
47 abstract class LockManager {
49  protected $logger;
50 
52  protected $lockTypeMap = [
53  self::LOCK_SH => self::LOCK_SH,
54  self::LOCK_UW => self::LOCK_EX, // subclasses may use self::LOCK_SH
55  self::LOCK_EX => self::LOCK_EX
56  ];
57 
59  protected $locksHeld = [];
60 
61  protected $domain; // string; domain (usually wiki ID)
62  protected $lockTTL; // integer; maximum time locks can be held
63 
65  protected $session;
66 
68  public const LOCK_SH = 1; // shared lock (for reads)
69  public const LOCK_UW = 2; // shared lock (for reads used to write elsewhere)
70  public const LOCK_EX = 3; // exclusive lock (for writes)
71 
73  protected const MAX_LOCK_TTL = 2 * 3600; // 2 hours
74 
76  protected const CLI_LOCK_TTL = 3600; // 1 hour
77 
79  protected const MIN_LOCK_TTL = 5; // seconds
80 
82  protected const MIN_GUESSED_LOCK_TTL = 5 * 60; // 5 minutes
83 
93  public function __construct( array $config ) {
94  $this->domain = $config['domain'] ?? 'global';
95  if ( isset( $config['lockTTL'] ) ) {
96  $this->lockTTL = max( self::MIN_LOCK_TTL, $config['lockTTL'] );
97  } elseif ( PHP_SAPI === 'cli' || PHP_SAPI === 'phpdbg' ) {
98  $this->lockTTL = self::CLI_LOCK_TTL;
99  } else {
100  $ttl = 2 * ceil( RequestTimeout::singleton()->getWallTimeLimit() );
101  $this->lockTTL = ( $ttl === INF || $ttl < self::MIN_GUESSED_LOCK_TTL )
102  ? self::MIN_GUESSED_LOCK_TTL : $ttl;
103  }
104 
105  // Upper bound on how long to keep lock structures around. This is useful when setting
106  // TTLs, as the "lockTTL" value may vary based on CLI mode and app server group. This is
107  // a "safe" value that can be used to avoid clobbering other locks that use high TTLs.
108  $this->lockTTL = min( $this->lockTTL, self::MAX_LOCK_TTL );
109 
110  $random = [];
111  for ( $i = 1; $i <= 5; ++$i ) {
112  $random[] = mt_rand( 0, 0xFFFFFFF );
113  }
114  $this->session = md5( implode( '-', $random ) );
115 
116  $this->logger = $config['logger'] ?? new NullLogger();
117  }
118 
127  final public function lock( array $paths, $type = self::LOCK_EX, $timeout = 0 ) {
128  return $this->lockByType( [ $type => $paths ], $timeout );
129  }
130 
139  final public function lockByType( array $pathsByType, $timeout = 0 ) {
140  $pathsByType = $this->normalizePathsByType( $pathsByType );
141 
142  $status = null;
143  $loop = new WaitConditionLoop(
144  function () use ( &$status, $pathsByType ) {
145  $status = $this->doLockByType( $pathsByType );
146 
147  return $status->isOK() ?: WaitConditionLoop::CONDITION_CONTINUE;
148  },
149  $timeout
150  );
151  $loop->invoke();
152 
153  // @phan-suppress-next-line PhanTypeMismatchReturn WaitConditionLoop throws or status is set
154  return $status;
155  }
156 
164  final public function unlock( array $paths, $type = self::LOCK_EX ) {
165  return $this->unlockByType( [ $type => $paths ] );
166  }
167 
175  final public function unlockByType( array $pathsByType ) {
176  $pathsByType = $this->normalizePathsByType( $pathsByType );
177  $status = $this->doUnlockByType( $pathsByType );
178 
179  return $status;
180  }
181 
190  final protected function sha1Base36Absolute( $path ) {
191  return Wikimedia\base_convert( sha1( "{$this->domain}:{$path}" ), 16, 36, 31 );
192  }
193 
202  final protected function sha1Base16Absolute( $path ) {
203  return sha1( "{$this->domain}:{$path}" );
204  }
205 
214  final protected function normalizePathsByType( array $pathsByType ) {
215  $res = [];
216  foreach ( $pathsByType as $type => $paths ) {
217  foreach ( $paths as $path ) {
218  if ( (string)$path === '' ) {
219  throw new InvalidArgumentException( __METHOD__ . ": got empty path." );
220  }
221  }
222  $res[$this->lockTypeMap[$type]] = array_unique( $paths );
223  }
224 
225  return $res;
226  }
227 
235  protected function doLockByType( array $pathsByType ) {
236  $status = StatusValue::newGood();
237  $lockedByType = []; // map of (type => paths)
238  foreach ( $pathsByType as $type => $paths ) {
239  $status->merge( $this->doLock( $paths, $type ) );
240  if ( $status->isOK() ) {
241  $lockedByType[$type] = $paths;
242  } else {
243  // Release the subset of locks that were acquired
244  foreach ( $lockedByType as $lType => $lPaths ) {
245  $status->merge( $this->doUnlock( $lPaths, $lType ) );
246  }
247  break;
248  }
249  }
250 
251  return $status;
252  }
253 
261  abstract protected function doLock( array $paths, $type );
262 
270  protected function doUnlockByType( array $pathsByType ) {
271  $status = StatusValue::newGood();
272  foreach ( $pathsByType as $type => $paths ) {
273  $status->merge( $this->doUnlock( $paths, $type ) );
274  }
275 
276  return $status;
277  }
278 
286  abstract protected function doUnlock( array $paths, $type );
287 }
Resource locking handling.
Definition: LockManager.php:47
const CLI_LOCK_TTL
Default lock TTL in CLI mode.
Definition: LockManager.php:76
doUnlockByType(array $pathsByType)
const MIN_LOCK_TTL
Minimum lock TTL.
Definition: LockManager.php:79
array $lockTypeMap
Mapping of lock types to the type actually used.
Definition: LockManager.php:52
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:82
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:65
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:68
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:49
const MAX_LOCK_TTL
Max expected lock expiry in any context.
Definition: LockManager.php:73
const LOCK_EX
Definition: LockManager.php:70
sha1Base36Absolute( $path)
Get the base 36 SHA-1 of a string, padded to 31 digits.
const LOCK_UW
Definition: LockManager.php:69
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:59
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:93
static newGood( $value=null)
Factory function for good results.
Definition: StatusValue.php:85