MediaWiki  master
LockManager.php
Go to the documentation of this file.
1 <?php
9 
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  const LOCK_SH = 1; // shared lock (for reads)
69  const LOCK_UW = 2; // shared lock (for reads used to write elsewhere)
70  const LOCK_EX = 3; // exclusive lock (for writes)
71 
73  const MAX_LOCK_TTL = 7200; // 2 hours
74 
83  public function __construct( array $config ) {
84  $this->domain = $config['domain'] ?? 'global';
85  if ( isset( $config['lockTTL'] ) ) {
86  $this->lockTTL = max( 5, $config['lockTTL'] );
87  } elseif ( PHP_SAPI === 'cli' || PHP_SAPI === 'phpdbg' ) {
88  $this->lockTTL = 3600;
89  } else {
90  $met = ini_get( 'max_execution_time' ); // this is 0 in CLI mode
91  $this->lockTTL = max( 5 * 60, 2 * (int)$met );
92  }
93 
94  // Upper bound on how long to keep lock structures around. This is useful when setting
95  // TTLs, as the "lockTTL" value may vary based on CLI mode and app server group. This is
96  // a "safe" value that can be used to avoid clobbering other locks that use high TTLs.
97  $this->lockTTL = min( $this->lockTTL, self::MAX_LOCK_TTL );
98 
99  $random = [];
100  for ( $i = 1; $i <= 5; ++$i ) {
101  $random[] = mt_rand( 0, 0xFFFFFFF );
102  }
103  $this->session = md5( implode( '-', $random ) );
104 
105  $this->logger = $config['logger'] ?? new NullLogger();
106  }
107 
116  final public function lock( array $paths, $type = self::LOCK_EX, $timeout = 0 ) {
117  return $this->lockByType( [ $type => $paths ], $timeout );
118  }
119 
128  final public function lockByType( array $pathsByType, $timeout = 0 ) {
129  $pathsByType = $this->normalizePathsByType( $pathsByType );
130 
131  $status = null;
132  $loop = new WaitConditionLoop(
133  function () use ( &$status, $pathsByType ) {
134  $status = $this->doLockByType( $pathsByType );
135 
136  return $status->isOK() ?: WaitConditionLoop::CONDITION_CONTINUE;
137  },
138  $timeout
139  );
140  $loop->invoke();
141 
142  return $status;
143  }
144 
152  final public function unlock( array $paths, $type = self::LOCK_EX ) {
153  return $this->unlockByType( [ $type => $paths ] );
154  }
155 
163  final public function unlockByType( array $pathsByType ) {
164  $pathsByType = $this->normalizePathsByType( $pathsByType );
165  $status = $this->doUnlockByType( $pathsByType );
166 
167  return $status;
168  }
169 
178  final protected function sha1Base36Absolute( $path ) {
179  return Wikimedia\base_convert( sha1( "{$this->domain}:{$path}" ), 16, 36, 31 );
180  }
181 
190  final protected function sha1Base16Absolute( $path ) {
191  return sha1( "{$this->domain}:{$path}" );
192  }
193 
202  final protected function normalizePathsByType( array $pathsByType ) {
203  $res = [];
204  foreach ( $pathsByType as $type => $paths ) {
205  foreach ( $paths as $path ) {
206  if ( (string)$path === '' ) {
207  throw new InvalidArgumentException( __METHOD__ . ": got empty path." );
208  }
209  }
210  $res[$this->lockTypeMap[$type]] = array_unique( $paths );
211  }
212 
213  return $res;
214  }
215 
222  protected function doLockByType( array $pathsByType ) {
223  $status = StatusValue::newGood();
224  $lockedByType = []; // map of (type => paths)
225  foreach ( $pathsByType as $type => $paths ) {
226  $status->merge( $this->doLock( $paths, $type ) );
227  if ( $status->isOK() ) {
228  $lockedByType[$type] = $paths;
229  } else {
230  // Release the subset of locks that were acquired
231  foreach ( $lockedByType as $lType => $lPaths ) {
232  $status->merge( $this->doUnlock( $lPaths, $lType ) );
233  }
234  break;
235  }
236  }
237 
238  return $status;
239  }
240 
248  abstract protected function doLock( array $paths, $type );
249 
256  protected function doUnlockByType( array $pathsByType ) {
257  $status = StatusValue::newGood();
258  foreach ( $pathsByType as $type => $paths ) {
259  $status->merge( $this->doUnlock( $paths, $type ) );
260  }
261 
262  return $status;
263  }
264 
272  abstract protected function doUnlock( array $paths, $type );
273 }
doUnlockByType(array $pathsByType)
unlockByType(array $pathsByType)
Unlock the resources at the given abstract paths.
LoggerInterface $logger
Definition: LockManager.php:49
__construct(array $config)
Construct a new instance from configuration.
Definition: LockManager.php:83
lock(array $paths, $type=self::LOCK_EX, $timeout=0)
Lock the resources at the given abstract paths.
string $session
Random 32-char hex number.
Definition: LockManager.php:65
doUnlock(array $paths, $type)
Unlock resources with the given keys and lock type.
const LOCK_UW
Definition: LockManager.php:69
const LOCK_EX
Definition: LockManager.php:70
static newGood( $value=null)
Factory function for good results.
Definition: StatusValue.php:81
array $locksHeld
Map of (resource path => lock type => count)
Definition: LockManager.php:59
doLock(array $paths, $type)
Lock resources with the given keys and lock type.
const LOCK_SH
Lock types; stronger locks have higher values.
Definition: LockManager.php:68
sha1Base16Absolute( $path)
Get the base 16 SHA-1 of a string, padded to 31 digits.
lockByType(array $pathsByType, $timeout=0)
Lock the resources at the given abstract paths.
normalizePathsByType(array $pathsByType)
Normalize the $paths array by converting LOCK_UW locks into the appropriate type and removing any dup...
doLockByType(array $pathsByType)
unlock(array $paths, $type=self::LOCK_EX)
Unlock the resources at the given abstract paths.
array $lockTypeMap
Mapping of lock types to the type actually used.
Definition: LockManager.php:52
sha1Base36Absolute( $path)
Get the base 36 SHA-1 of a string, padded to 31 digits.