MediaWiki  master
QuorumLockManager.php
Go to the documentation of this file.
1 <?php
31 abstract class QuorumLockManager extends LockManager {
33  protected $srvsByBucket = []; // (bucket index => (lsrv1, lsrv2, ...))
34 
36  protected $degradedBuckets = []; // (bucket index => UNIX timestamp)
37 
38  final protected function doLockByType( array $pathsByType ) {
39  $status = StatusValue::newGood();
40 
41  $pathsByTypeByBucket = []; // (bucket => type => paths)
42  // Get locks that need to be acquired (buckets => locks)...
43  foreach ( $pathsByType as $type => $paths ) {
44  foreach ( $paths as $path ) {
45  if ( isset( $this->locksHeld[$path][$type] ) ) {
46  ++$this->locksHeld[$path][$type];
47  } else {
48  $bucket = $this->getBucketFromPath( $path );
49  $pathsByTypeByBucket[$bucket][$type][] = $path;
50  }
51  }
52  }
53 
54  // Acquire locks in each bucket in bucket order to reduce contention. Any blocking
55  // mutexes during the acquisition step will not involve circular waiting on buckets.
56  ksort( $pathsByTypeByBucket );
57 
58  $lockedPaths = []; // files locked in this attempt (type => paths)
59  // Attempt to acquire these locks...
60  foreach ( $pathsByTypeByBucket as $bucket => $bucketPathsByType ) {
61  // Try to acquire the locks for this bucket
62  $status->merge( $this->doLockingRequestBucket( $bucket, $bucketPathsByType ) );
63  if ( !$status->isOK() ) {
64  $status->merge( $this->doUnlockByType( $lockedPaths ) );
65 
66  return $status;
67  }
68  // Record these locks as active
69  foreach ( $bucketPathsByType as $type => $paths ) {
70  foreach ( $paths as $path ) {
71  $this->locksHeld[$path][$type] = 1; // locked
72  // Keep track of what locks were made in this attempt
73  $lockedPaths[$type][] = $path;
74  }
75  }
76  }
77 
78  return $status;
79  }
80 
81  protected function doUnlockByType( array $pathsByType ) {
82  $status = StatusValue::newGood();
83 
84  $pathsByTypeByBucket = []; // (bucket => type => paths)
85  foreach ( $pathsByType as $type => $paths ) {
86  foreach ( $paths as $path ) {
87  if ( !isset( $this->locksHeld[$path][$type] ) ) {
88  $status->warning( 'lockmanager-notlocked', $path );
89  } else {
90  --$this->locksHeld[$path][$type];
91  // Reference count the locks held and release locks when zero
92  if ( $this->locksHeld[$path][$type] <= 0 ) {
93  unset( $this->locksHeld[$path][$type] );
94  $bucket = $this->getBucketFromPath( $path );
95  $pathsByTypeByBucket[$bucket][$type][] = $path;
96  }
97  if ( $this->locksHeld[$path] === [] ) {
98  unset( $this->locksHeld[$path] ); // no SH or EX locks left for key
99  }
100  }
101  }
102  }
103 
104  // Remove these specific locks if possible, or at least release
105  // all locks once this process is currently not holding any locks.
106  foreach ( $pathsByTypeByBucket as $bucket => $bucketPathsByType ) {
107  $status->merge( $this->doUnlockingRequestBucket( $bucket, $bucketPathsByType ) );
108  }
109  if ( $this->locksHeld === [] ) {
110  $status->merge( $this->releaseAllLocks() );
111  $this->degradedBuckets = []; // safe to retry the normal quorum
112  }
113 
114  return $status;
115  }
116 
125  final protected function doLockingRequestBucket( $bucket, array $pathsByType ) {
126  return $this->collectPledgeQuorum(
127  $bucket,
128  function ( $lockSrv ) use ( $pathsByType ) {
129  return $this->getLocksOnServer( $lockSrv, $pathsByType );
130  }
131  );
132  }
133 
141  final protected function doUnlockingRequestBucket( $bucket, array $pathsByType ) {
142  return $this->releasePledges(
143  $bucket,
144  function ( $lockSrv ) use ( $pathsByType ) {
145  return $this->freeLocksOnServer( $lockSrv, $pathsByType );
146  }
147  );
148  }
149 
158  final protected function collectPledgeQuorum( $bucket, callable $callback ) {
159  $status = StatusValue::newGood();
160 
161  $yesVotes = 0; // locks made on trustable servers
162  $votesLeft = count( $this->srvsByBucket[$bucket] ); // remaining peers
163  $quorum = floor( $votesLeft / 2 + 1 ); // simple majority
164  // Get votes for each peer, in order, until we have enough...
165  foreach ( $this->srvsByBucket[$bucket] as $lockSrv ) {
166  if ( !$this->isServerUp( $lockSrv ) ) {
167  --$votesLeft;
168  $status->warning( 'lockmanager-fail-svr-acquire', $lockSrv );
169  $this->degradedBuckets[$bucket] = time();
170  continue; // server down?
171  }
172  // Attempt to acquire the lock on this peer
173  $status->merge( $callback( $lockSrv ) );
174  if ( !$status->isOK() ) {
175  return $status; // vetoed; resource locked
176  }
177  ++$yesVotes; // success for this peer
178  if ( $yesVotes >= $quorum ) {
179  return $status; // lock obtained
180  }
181  --$votesLeft;
182  $votesNeeded = $quorum - $yesVotes;
183  if ( $votesNeeded > $votesLeft ) {
184  break; // short-circuit
185  }
186  }
187  // At this point, we must not have met the quorum
188  $status->setResult( false );
189 
190  return $status;
191  }
192 
200  final protected function releasePledges( $bucket, callable $callback ) {
201  $status = StatusValue::newGood();
202 
203  $yesVotes = 0; // locks freed on trustable servers
204  $votesLeft = count( $this->srvsByBucket[$bucket] ); // remaining peers
205  $quorum = floor( $votesLeft / 2 + 1 ); // simple majority
206  $isDegraded = isset( $this->degradedBuckets[$bucket] ); // not the normal quorum?
207  foreach ( $this->srvsByBucket[$bucket] as $lockSrv ) {
208  if ( !$this->isServerUp( $lockSrv ) ) {
209  $status->warning( 'lockmanager-fail-svr-release', $lockSrv );
210  } else {
211  // Attempt to release the lock on this peer
212  $status->merge( $callback( $lockSrv ) );
213  ++$yesVotes; // success for this peer
214  // Normally the first peers form the quorum, and the others are ignored.
215  // Ignore them in this case, but not when an alternative quorum was used.
216  if ( $yesVotes >= $quorum && !$isDegraded ) {
217  break; // lock released
218  }
219  }
220  }
221  // Set a bad StatusValue if the quorum was not met.
222  // Assumes the same "up" servers as during the acquire step.
223  $status->setResult( $yesVotes >= $quorum );
224 
225  return $status;
226  }
227 
235  protected function getBucketFromPath( $path ) {
236  $prefix = substr( sha1( $path ), 0, 2 ); // first 2 hex chars (8 bits)
237  return (int)base_convert( $prefix, 16, 10 ) % count( $this->srvsByBucket );
238  }
239 
247  abstract protected function isServerUp( $lockSrv );
248 
256  abstract protected function getLocksOnServer( $lockSrv, array $pathsByType );
257 
267  abstract protected function freeLocksOnServer( $lockSrv, array $pathsByType );
268 
276  abstract protected function releaseAllLocks();
277 
278  final protected function doLock( array $paths, $type ) {
279  throw new LogicException( __METHOD__ . ': proxy class does not need this method.' );
280  }
281 
282  final protected function doUnlock( array $paths, $type ) {
283  throw new LogicException( __METHOD__ . ': proxy class does not need this method.' );
284  }
285 }
getBucketFromPath( $path)
Get the bucket for resource path.
isServerUp( $lockSrv)
Check if a lock server is up.
releaseAllLocks()
Release all locks that this session is holding.
releasePledges( $bucket, callable $callback)
Attempt to release pledges with the peers for a bucket.
array $srvsByBucket
Map of bucket indexes to peer server lists.
array $degradedBuckets
Map of degraded buckets.
doUnlockingRequestBucket( $bucket, array $pathsByType)
Attempt to release locks with the peers for a bucket.
doUnlockByType(array $pathsByType)
static newGood( $value=null)
Factory function for good results.
Definition: StatusValue.php:81
doUnlock(array $paths, $type)
freeLocksOnServer( $lockSrv, array $pathsByType)
Get a connection to a lock server and release locks on $paths.
doLock(array $paths, $type)
doLockByType(array $pathsByType)
doLockingRequestBucket( $bucket, array $pathsByType)
Attempt to acquire locks with the peers for a bucket.
collectPledgeQuorum( $bucket, callable $callback)
Attempt to acquire pledges with the peers for a bucket.
getLocksOnServer( $lockSrv, array $pathsByType)
Get a connection to a lock server and acquire locks.
Version of LockManager that uses a quorum from peer servers for locks.