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\WaitConditionLoop;
9 
48 abstract class LockManager {
50  protected $logger;
51 
53  protected $lockTypeMap = [
54  self::LOCK_SH => self::LOCK_SH,
55  self::LOCK_UW => self::LOCK_EX, // subclasses may use self::LOCK_SH
56  self::LOCK_EX => self::LOCK_EX
57  ];
58 
60  protected $locksHeld = [];
61 
62  protected $domain; // string; domain (usually wiki ID)
63  protected $lockTTL; // integer; maximum time locks can be held
64 
66  protected $session;
67 
69  public const LOCK_SH = 1; // shared lock (for reads)
70  public const LOCK_UW = 2; // shared lock (for reads used to write elsewhere)
71  public const LOCK_EX = 3; // exclusive lock (for writes)
72 
74  protected const MAX_LOCK_TTL = 7200; // 2 hours
75 
85  public function __construct( array $config ) {
86  $this->domain = $config['domain'] ?? 'global';
87  if ( isset( $config['lockTTL'] ) ) {
88  $this->lockTTL = max( 5, $config['lockTTL'] );
89  } elseif ( PHP_SAPI === 'cli' || PHP_SAPI === 'phpdbg' ) {
90  $this->lockTTL = 3600;
91  } else {
92  $met = ini_get( 'max_execution_time' ); // this is 0 in CLI mode
93  $this->lockTTL = max( 5 * 60, 2 * (int)$met );
94  }
95 
96  // Upper bound on how long to keep lock structures around. This is useful when setting
97  // TTLs, as the "lockTTL" value may vary based on CLI mode and app server group. This is
98  // a "safe" value that can be used to avoid clobbering other locks that use high TTLs.
99  $this->lockTTL = min( $this->lockTTL, self::MAX_LOCK_TTL );
100 
101  $random = [];
102  for ( $i = 1; $i <= 5; ++$i ) {
103  $random[] = mt_rand( 0, 0xFFFFFFF );
104  }
105  $this->session = md5( implode( '-', $random ) );
106 
107  $this->logger = $config['logger'] ?? new NullLogger();
108  }
109 
118  final public function lock( array $paths, $type = self::LOCK_EX, $timeout = 0 ) {
119  return $this->lockByType( [ $type => $paths ], $timeout );
120  }
121 
130  final public function lockByType( array $pathsByType, $timeout = 0 ) {
131  $pathsByType = $this->normalizePathsByType( $pathsByType );
132 
133  $status = null;
134  $loop = new WaitConditionLoop(
135  function () use ( &$status, $pathsByType ) {
136  $status = $this->doLockByType( $pathsByType );
137 
138  return $status->isOK() ?: WaitConditionLoop::CONDITION_CONTINUE;
139  },
140  $timeout
141  );
142  $loop->invoke();
143 
144  return $status;
145  }
146 
154  final public function unlock( array $paths, $type = self::LOCK_EX ) {
155  return $this->unlockByType( [ $type => $paths ] );
156  }
157 
165  final public function unlockByType( array $pathsByType ) {
166  $pathsByType = $this->normalizePathsByType( $pathsByType );
167  $status = $this->doUnlockByType( $pathsByType );
168 
169  return $status;
170  }
171 
180  final protected function sha1Base36Absolute( $path ) {
181  return Wikimedia\base_convert( sha1( "{$this->domain}:{$path}" ), 16, 36, 31 );
182  }
183 
192  final protected function sha1Base16Absolute( $path ) {
193  return sha1( "{$this->domain}:{$path}" );
194  }
195 
204  final protected function normalizePathsByType( array $pathsByType ) {
205  $res = [];
206  foreach ( $pathsByType as $type => $paths ) {
207  foreach ( $paths as $path ) {
208  if ( (string)$path === '' ) {
209  throw new InvalidArgumentException( __METHOD__ . ": got empty path." );
210  }
211  }
212  $res[$this->lockTypeMap[$type]] = array_unique( $paths );
213  }
214 
215  return $res;
216  }
217 
225  protected function doLockByType( array $pathsByType ) {
226  $status = StatusValue::newGood();
227  $lockedByType = []; // map of (type => paths)
228  foreach ( $pathsByType as $type => $paths ) {
229  $status->merge( $this->doLock( $paths, $type ) );
230  if ( $status->isOK() ) {
231  $lockedByType[$type] = $paths;
232  } else {
233  // Release the subset of locks that were acquired
234  foreach ( $lockedByType as $lType => $lPaths ) {
235  $status->merge( $this->doUnlock( $lPaths, $lType ) );
236  }
237  break;
238  }
239  }
240 
241  return $status;
242  }
243 
251  abstract protected function doLock( array $paths, $type );
252 
260  protected function doUnlockByType( array $pathsByType ) {
261  $status = StatusValue::newGood();
262  foreach ( $pathsByType as $type => $paths ) {
263  $status->merge( $this->doUnlock( $paths, $type ) );
264  }
265 
266  return $status;
267  }
268 
276  abstract protected function doUnlock( array $paths, $type );
277 }
LockManager
Class for handling resource locking.
Definition: LockManager.php:48
LockManager\$locksHeld
array $locksHeld
Map of (resource path => lock type => count)
Definition: LockManager.php:60
LockManager\LOCK_SH
const LOCK_SH
Lock types; stronger locks have higher values.
Definition: LockManager.php:69
LockManager\sha1Base16Absolute
sha1Base16Absolute( $path)
Get the base 16 SHA-1 of a string, padded to 31 digits.
Definition: LockManager.php:192
LockManager\LOCK_UW
const LOCK_UW
Definition: LockManager.php:70
$res
$res
Definition: testCompression.php:57
LockManager\$lockTypeMap
array $lockTypeMap
Mapping of lock types to the type actually used.
Definition: LockManager.php:53
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:204
LockManager\$lockTTL
$lockTTL
Definition: LockManager.php:63
LockManager\sha1Base36Absolute
sha1Base36Absolute( $path)
Get the base 36 SHA-1 of a string, padded to 31 digits.
Definition: LockManager.php:180
LockManager\doUnlockByType
doUnlockByType(array $pathsByType)
Definition: LockManager.php:260
LockManager\unlock
unlock(array $paths, $type=self::LOCK_EX)
Unlock the resources at the given abstract paths.
Definition: LockManager.php:154
LockManager\lock
lock(array $paths, $type=self::LOCK_EX, $timeout=0)
Lock the resources at the given abstract paths.
Definition: LockManager.php:118
LockManager\unlockByType
unlockByType(array $pathsByType)
Unlock the resources at the given abstract paths.
Definition: LockManager.php:165
StatusValue\newGood
static newGood( $value=null)
Factory function for good results.
Definition: StatusValue.php:82
LockManager\$logger
LoggerInterface $logger
Definition: LockManager.php:50
LockManager\$session
string $session
Random 32-char hex number.
Definition: LockManager.php:66
LockManager\doUnlock
doUnlock(array $paths, $type)
Unlock resources with the given keys and lock type.
$path
$path
Definition: NoLocalSettings.php:25
LockManager\__construct
__construct(array $config)
Construct a new instance from configuration Stable to call.
Definition: LockManager.php:85
LockManager\LOCK_EX
const LOCK_EX
Definition: LockManager.php:71
LockManager\doLock
doLock(array $paths, $type)
Lock resources with the given keys and lock type.
LockManager\doLockByType
doLockByType(array $pathsByType)
Definition: LockManager.php:225
LockManager\lockByType
lockByType(array $pathsByType, $timeout=0)
Lock the resources at the given abstract paths.
Definition: LockManager.php:130
LockManager\$domain
$domain
Definition: LockManager.php:62
$type
$type
Definition: testCompression.php:52