includes/filerepo/backend/lockmanager/LockManager.php

   1 <?php
   2 /**
   3  * @defgroup LockManager Lock management
   4  * @ingroup FileBackend
   5  */
   6
   7 /**
   8  * Resource locking handling.
   9  *
  10  * This program is free software; you can redistribute it and/or modify
  11  * it under the terms of the GNU General Public License as published by
  12  * the Free Software Foundation; either version 2 of the License, or
  13  * (at your option) any later version.
  14  *
  15  * This program is distributed in the hope that it will be useful,
  16  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  17  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  18  * GNU General Public License for more details.
  19  *
  20  * You should have received a copy of the GNU General Public License along
  21  * with this program; if not, write to the Free Software Foundation, Inc.,
  22  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  23  * http://www.gnu.org/copyleft/gpl.html
  24  *
  25  * @file
  26  * @ingroup LockManager
  27  * @author Aaron Schulz
  28  */
  29
  30 /**
  31  * @brief Class for handling resource locking.
  32  *
  33  * Locks on resource keys can either be shared or exclusive.
  34  *
  35  * Implementations must keep track of what is locked by this proccess
  36  * in-memory and support nested locking calls (using reference counting).
  37  * At least LOCK_UW and LOCK_EX must be implemented. LOCK_SH can be a no-op.
  38  * Locks should either be non-blocking or have low wait timeouts.
  39  *
  40  * Subclasses should avoid throwing exceptions at all costs.
  41  *
  42  * @ingroup LockManager
  43  * @since 1.19
  44  */
  45 abstract class LockManager {
  46         /** @var Array Mapping of lock types to the type actually used */
  47         protected $lockTypeMap = array(
  48                 self::LOCK_SH => self::LOCK_SH,
  49                 self::LOCK_UW => self::LOCK_EX, // subclasses may use self::LOCK_SH
  50                 self::LOCK_EX => self::LOCK_EX
  51         );
  52
  53         /** @var Array Map of (resource path => lock type => count) */
  54         protected $locksHeld = array();
  55
  56         /* Lock types; stronger locks have higher values */
  57         const LOCK_SH = 1; // shared lock (for reads)
  58         const LOCK_UW = 2; // shared lock (for reads used to write elsewhere)
  59         const LOCK_EX = 3; // exclusive lock (for writes)
  60
  61         /**
  62          * Construct a new instance from configuration
  63          *
  64          * @param $config Array
  65          */
  66         public function __construct( array $config ) {}
  67
  68         /**
  69          * Lock the resources at the given abstract paths
  70          *
  71          * @param $paths Array List of resource names
  72          * @param $type integer LockManager::LOCK_* constant
  73          * @return Status
  74          */
  75         final public function lock( array $paths, $type = self::LOCK_EX ) {
  76                 wfProfileIn( __METHOD__ );
  77                 $status = $this->doLock( array_unique( $paths ), $this->lockTypeMap[$type] );
  78                 wfProfileOut( __METHOD__ );
  79                 return $status;
  80         }
  81
  82         /**
  83          * Unlock the resources at the given abstract paths
  84          *
  85          * @param $paths Array List of storage paths
  86          * @param $type integer LockManager::LOCK_* constant
  87          * @return Status
  88          */
  89         final public function unlock( array $paths, $type = self::LOCK_EX ) {
  90                 wfProfileIn( __METHOD__ );
  91                 $status = $this->doUnlock( array_unique( $paths ), $this->lockTypeMap[$type] );
  92                 wfProfileOut( __METHOD__ );
  93                 return $status;
  94         }
  95
  96         /**
  97          * Get the base 36 SHA-1 of a string, padded to 31 digits
  98          *
  99          * @param $path string
 100          * @return string
 101          */
 102         final protected static function sha1Base36( $path ) {
 103                 return wfBaseConvert( sha1( $path ), 16, 36, 31 );
 104         }
 105
 106         /**
 107          * Lock resources with the given keys and lock type
 108          *
 109          * @param $paths Array List of storage paths
 110          * @param $type integer LockManager::LOCK_* constant
 111          * @return string
 112          */
 113         abstract protected function doLock( array $paths, $type );
 114
 115         /**
 116          * Unlock resources with the given keys and lock type
 117          *
 118          * @param $paths Array List of storage paths
 119          * @param $type integer LockManager::LOCK_* constant
 120          * @return string
 121          */
 122         abstract protected function doUnlock( array $paths, $type );
 123 }
 124
 125 /**
 126  * Self-releasing locks
 127  *
 128  * LockManager helper class to handle scoped locks, which
 129  * release when an object is destroyed or goes out of scope.
 130  *
 131  * @ingroup LockManager
 132  * @since 1.19
 133  */
 134 class ScopedLock {
 135         /** @var LockManager */
 136         protected $manager;
 137         /** @var Status */
 138         protected $status;
 139         /** @var Array List of resource paths*/
 140         protected $paths;
 141
 142         protected $type; // integer lock type
 143
 144         /**
 145          * @param $manager LockManager
 146          * @param $paths Array List of storage paths
 147          * @param $type integer LockManager::LOCK_* constant
 148          * @param $status Status
 149          */
 150         protected function __construct(
 151                 LockManager $manager, array $paths, $type, Status $status
 152         ) {
 153                 $this->manager = $manager;
 154                 $this->paths = $paths;
 155                 $this->status = $status;
 156                 $this->type = $type;
 157         }
 158
 159         /**
 160          * Get a ScopedLock object representing a lock on resource paths.
 161          * Any locks are released once this object goes out of scope.
 162          * The status object is updated with any errors or warnings.
 163          *
 164          * @param $manager LockManager
 165          * @param $paths Array List of storage paths
 166          * @param $type integer LockManager::LOCK_* constant
 167          * @param $status Status
 168          * @return ScopedLock|null Returns null on failure
 169          */
 170         public static function factory(
 171                 LockManager $manager, array $paths, $type, Status $status
 172         ) {
 173                 $lockStatus = $manager->lock( $paths, $type );
 174                 $status->merge( $lockStatus );
 175                 if ( $lockStatus->isOK() ) {
 176                         return new self( $manager, $paths, $type, $status );
 177                 }
 178                 return null;
 179         }
 180
 181         function __destruct() {
 182                 $wasOk = $this->status->isOK();
 183                 $this->status->merge( $this->manager->unlock( $this->paths, $this->type ) );
 184                 if ( $wasOk ) {
 185                         // Make sure status is OK, despite any unlockFiles() fatals
 186                         $this->status->setResult( true, $this->status->value );
 187                 }
 188         }
 189 }
 190
 191 /**
 192  * Version of LockManager that uses a quorum from peer servers for locks.
 193  * The resource space can also be sharded into separate peer groups.
 194  *
 195  * @ingroup LockManager
 196  * @since 1.20
 197  */
 198 abstract class QuorumLockManager extends LockManager {
 199         /** @var Array Map of bucket indexes to peer server lists */
 200         protected $srvsByBucket = array(); // (bucket index => (lsrv1, lsrv2, ...))
 201
 202         /**
 203          * @see LockManager::doLock()
 204          * @param $paths array
 205          * @param $type int
 206          * @return Status
 207          */
 208         final protected function doLock( array $paths, $type ) {
 209                 $status = Status::newGood();
 210
 211                 $pathsToLock = array(); // (bucket => paths)
 212                 // Get locks that need to be acquired (buckets => locks)...
 213                 foreach ( $paths as $path ) {
 214                         if ( isset( $this->locksHeld[$path][$type] ) ) {
 215                                 ++$this->locksHeld[$path][$type];
 216                         } elseif ( isset( $this->locksHeld[$path][self::LOCK_EX] ) ) {
 217                                 $this->locksHeld[$path][$type] = 1;
 218                         } else {
 219                                 $bucket = $this->getBucketFromKey( $path );
 220                                 $pathsToLock[$bucket][] = $path;
 221                         }
 222                 }
 223
 224                 $lockedPaths = array(); // files locked in this attempt
 225                 // Attempt to acquire these locks...
 226                 foreach ( $pathsToLock as $bucket => $paths ) {
 227                         // Try to acquire the locks for this bucket
 228                         $status->merge( $this->doLockingRequestBucket( $bucket, $paths, $type ) );
 229                         if ( !$status->isOK() ) {
 230                                 $status->merge( $this->doUnlock( $lockedPaths, $type ) );
 231                                 return $status;
 232                         }
 233                         // Record these locks as active
 234                         foreach ( $paths as $path ) {
 235                                 $this->locksHeld[$path][$type] = 1; // locked
 236                         }
 237                         // Keep track of what locks were made in this attempt
 238                         $lockedPaths = array_merge( $lockedPaths, $paths );
 239                 }
 240
 241                 return $status;
 242         }
 243
 244         /**
 245          * @see LockManager::doUnlock()
 246          * @param $paths array
 247          * @param $type int
 248          * @return Status
 249          */
 250         final protected function doUnlock( array $paths, $type ) {
 251                 $status = Status::newGood();
 252
 253                 $pathsToUnlock = array();
 254                 foreach ( $paths as $path ) {
 255                         if ( !isset( $this->locksHeld[$path][$type] ) ) {
 256                                 $status->warning( 'lockmanager-notlocked', $path );
 257                         } else {
 258                                 --$this->locksHeld[$path][$type];
 259                                 // Reference count the locks held and release locks when zero
 260                                 if ( $this->locksHeld[$path][$type] <= 0 ) {
 261                                         unset( $this->locksHeld[$path][$type] );
 262                                         $bucket = $this->getBucketFromKey( $path );
 263                                         $pathsToUnlock[$bucket][] = $path;
 264                                 }
 265                                 if ( !count( $this->locksHeld[$path] ) ) {
 266                                         unset( $this->locksHeld[$path] ); // no SH or EX locks left for key
 267                                 }
 268                         }
 269                 }
 270
 271                 // Remove these specific locks if possible, or at least release
 272                 // all locks once this process is currently not holding any locks.
 273                 foreach ( $pathsToUnlock as $bucket => $paths ) {
 274                         $status->merge( $this->doUnlockingRequestBucket( $bucket, $paths, $type ) );
 275                 }
 276                 if ( !count( $this->locksHeld ) ) {
 277                         $status->merge( $this->releaseAllLocks() );
 278                 }
 279
 280                 return $status;
 281         }
 282
 283         /**
 284          * Attempt to acquire locks with the peers for a bucket.
 285          * This is all or nothing; if any key is locked then this totally fails.
 286          *
 287          * @param $bucket integer
 288          * @param $paths Array List of resource keys to lock
 289          * @param $type integer LockManager::LOCK_EX or LockManager::LOCK_SH
 290          * @return Status
 291          */
 292         final protected function doLockingRequestBucket( $bucket, array $paths, $type ) {
 293                 $status = Status::newGood();
 294
 295                 $yesVotes = 0; // locks made on trustable servers
 296                 $votesLeft = count( $this->srvsByBucket[$bucket] ); // remaining peers
 297                 $quorum = floor( $votesLeft/2 + 1 ); // simple majority
 298                 // Get votes for each peer, in order, until we have enough...
 299                 foreach ( $this->srvsByBucket[$bucket] as $lockSrv ) {
 300                         if ( !$this->isServerUp( $lockSrv ) ) {
 301                                 --$votesLeft;
 302                                 $status->warning( 'lockmanager-fail-svr-acquire', $lockSrv );
 303                                 continue; // server down?
 304                         }
 305                         // Attempt to acquire the lock on this peer
 306                         $status->merge( $this->getLocksOnServer( $lockSrv, $paths, $type ) );
 307                         if ( !$status->isOK() ) {
 308                                 return $status; // vetoed; resource locked
 309                         }
 310                         ++$yesVotes; // success for this peer
 311                         if ( $yesVotes >= $quorum ) {
 312                                 return $status; // lock obtained
 313                         }
 314                         --$votesLeft;
 315                         $votesNeeded = $quorum - $yesVotes;
 316                         if ( $votesNeeded > $votesLeft ) {
 317                                 break; // short-circuit
 318                         }
 319                 }
 320                 // At this point, we must not have met the quorum
 321                 $status->setResult( false );
 322
 323                 return $status;
 324         }
 325
 326         /**
 327          * Attempt to release locks with the peers for a bucket
 328          *
 329          * @param $bucket integer
 330          * @param $paths Array List of resource keys to lock
 331          * @param $type integer LockManager::LOCK_EX or LockManager::LOCK_SH
 332          * @return Status
 333          */
 334         final protected function doUnlockingRequestBucket( $bucket, array $paths, $type ) {
 335                 $status = Status::newGood();
 336
 337                 foreach ( $this->srvsByBucket[$bucket] as $lockSrv ) {
 338                         if ( !$this->isServerUp( $lockSrv ) ) {
 339                                 $status->fatal( 'lockmanager-fail-svr-release', $lockSrv );
 340                         // Attempt to release the lock on this peer
 341                         } else {
 342                                 $status->merge( $this->freeLocksOnServer( $lockSrv, $paths, $type ) );
 343                         }
 344                 }
 345
 346                 return $status;
 347         }
 348
 349         /**
 350          * Get the bucket for resource path.
 351          * This should avoid throwing any exceptions.
 352          *
 353          * @param $path string
 354          * @return integer
 355          */
 356         protected function getBucketFromKey( $path ) {
 357                 $prefix = substr( sha1( $path ), 0, 2 ); // first 2 hex chars (8 bits)
 358                 return (int)base_convert( $prefix, 16, 10 ) % count( $this->srvsByBucket );
 359         }
 360
 361         /**
 362          * Check if a lock server is up
 363          *
 364          * @param $lockSrv string
 365          * @return bool
 366          */
 367         abstract protected function isServerUp( $lockSrv );
 368
 369         /**
 370          * Get a connection to a lock server and acquire locks on $paths
 371          *
 372          * @param $lockSrv string
 373          * @param $paths array
 374          * @param $type integer
 375          * @return Status
 376          */
 377         abstract protected function getLocksOnServer( $lockSrv, array $paths, $type );
 378
 379         /**
 380          * Get a connection to a lock server and release locks on $paths.
 381          *
 382          * Subclasses must effectively implement this or releaseAllLocks().
 383          *
 384          * @param $lockSrv string
 385          * @param $paths array
 386          * @param $type integer
 387          * @return Status
 388          */
 389         abstract protected function freeLocksOnServer( $lockSrv, array $paths, $type );
 390
 391         /**
 392          * Release all locks that this session is holding.
 393          *
 394          * Subclasses must effectively implement this or freeLocksOnServer().
 395          *
 396          * @return Status
 397          */
 398         abstract protected function releaseAllLocks();
 399 }
 400
 401 /**
 402  * Simple version of LockManager that does nothing
 403  * @since 1.19
 404  */
 405 class NullLockManager extends LockManager {
 406         /**
 407          * @see LockManager::doLock()
 408          * @param $paths array
 409          * @param $type int
 410          * @return Status
 411          */
 412         protected function doLock( array $paths, $type ) {
 413                 return Status::newGood();
 414         }
 415
 416         /**
 417          * @see LockManager::doUnlock()
 418          * @param $paths array
 419          * @param $type int
 420          * @return Status
 421          */
 422         protected function doUnlock( array $paths, $type ) {
 423                 return Status::newGood();
 424         }
 425 }