includes/filerepo/backend/lockmanager/LockManager.php

   1 <?php
   2 /**
   3  * @defgroup LockManager Lock management
   4  * @ingroup FileBackend
   5  */
   6
   7 /**
   8  * @file
   9  * @ingroup LockManager
  10  * @author Aaron Schulz
  11  */
  12
  13 /**
  14  * Class for handling resource locking.
  15  *
  16  * Locks on resource keys can either be shared or exclusive.
  17  *
  18  * Implementations must keep track of what is locked by this proccess
  19  * in-memory and support nested locking calls (using reference counting).
  20  * At least LOCK_UW and LOCK_EX must be implemented. LOCK_SH can be a no-op.
  21  * Locks should either be non-blocking or have low wait timeouts.
  22  *
  23  * Subclasses should avoid throwing exceptions at all costs.
  24  *
  25  * @ingroup LockManager
  26  * @since 1.19
  27  */
  28 abstract class LockManager {
  29         /** @var Array Mapping of lock types to the type actually used */
  30         protected $lockTypeMap = array(
  31                 self::LOCK_SH => self::LOCK_SH,
  32                 self::LOCK_UW => self::LOCK_EX, // subclasses may use self::LOCK_SH
  33                 self::LOCK_EX => self::LOCK_EX
  34         );
  35
  36         /** @var Array Map of (resource path => lock type => count) */
  37         protected $locksHeld = array();
  38
  39         /* Lock types; stronger locks have higher values */
  40         const LOCK_SH = 1; // shared lock (for reads)
  41         const LOCK_UW = 2; // shared lock (for reads used to write elsewhere)
  42         const LOCK_EX = 3; // exclusive lock (for writes)
  43
  44         /**
  45          * Construct a new instance from configuration
  46          *
  47          * @param $config Array
  48          */
  49         public function __construct( array $config ) {}
  50
  51         /**
  52          * Lock the resources at the given abstract paths
  53          *
  54          * @param $paths Array List of resource names
  55          * @param $type integer LockManager::LOCK_* constant
  56          * @return Status
  57          */
  58         final public function lock( array $paths, $type = self::LOCK_EX ) {
  59                 return $this->doLock( array_unique( $paths ), $this->lockTypeMap[$type] );
  60         }
  61
  62         /**
  63          * Unlock the resources at the given abstract paths
  64          *
  65          * @param $paths Array List of storage paths
  66          * @param $type integer LockManager::LOCK_* constant
  67          * @return Status
  68          */
  69         final public function unlock( array $paths, $type = self::LOCK_EX ) {
  70                 return $this->doUnlock( array_unique( $paths ), $this->lockTypeMap[$type] );
  71         }
  72
  73         /**
  74          * Get the base 36 SHA-1 of a string, padded to 31 digits
  75          *
  76          * @param $path string
  77          * @return string
  78          */
  79         final protected static function sha1Base36( $path ) {
  80                 return wfBaseConvert( sha1( $path ), 16, 36, 31 );
  81         }
  82
  83         /**
  84          * Lock resources with the given keys and lock type
  85          *
  86          * @param $paths Array List of storage paths
  87          * @param $type integer LockManager::LOCK_* constant
  88          * @return string
  89          */
  90         abstract protected function doLock( array $paths, $type );
  91
  92         /**
  93          * Unlock resources with the given keys and lock type
  94          *
  95          * @param $paths Array List of storage paths
  96          * @param $type integer LockManager::LOCK_* constant
  97          * @return string
  98          */
  99         abstract protected function doUnlock( array $paths, $type );
 100 }
 101
 102 /**
 103  * Self releasing locks
 104  *
 105  * LockManager helper class to handle scoped locks, which
 106  * release when an object is destroyed or goes out of scope.
 107  *
 108  * @ingroup LockManager
 109  * @since 1.19
 110  */
 111 class ScopedLock {
 112         /** @var LockManager */
 113         protected $manager;
 114         /** @var Status */
 115         protected $status;
 116         /** @var Array List of resource paths*/
 117         protected $paths;
 118
 119         protected $type; // integer lock type
 120
 121         /**
 122          * @param $manager LockManager
 123          * @param $paths Array List of storage paths
 124          * @param $type integer LockManager::LOCK_* constant
 125          * @param $status Status
 126          */
 127         protected function __construct(
 128                 LockManager $manager, array $paths, $type, Status $status
 129         ) {
 130                 $this->manager = $manager;
 131                 $this->paths = $paths;
 132                 $this->status = $status;
 133                 $this->type = $type;
 134         }
 135
 136         protected function __clone() {}
 137
 138         /**
 139          * Get a ScopedLock object representing a lock on resource paths.
 140          * Any locks are released once this object goes out of scope.
 141          * The status object is updated with any errors or warnings.
 142          *
 143          * @param $manager LockManager
 144          * @param $paths Array List of storage paths
 145          * @param $type integer LockManager::LOCK_* constant
 146          * @param $status Status
 147          * @return ScopedLock|null Returns null on failure
 148          */
 149         public static function factory(
 150                 LockManager $manager, array $paths, $type, Status $status
 151         ) {
 152                 $lockStatus = $manager->lock( $paths, $type );
 153                 $status->merge( $lockStatus );
 154                 if ( $lockStatus->isOK() ) {
 155                         return new self( $manager, $paths, $type, $status );
 156                 }
 157                 return null;
 158         }
 159
 160         function __destruct() {
 161                 $wasOk = $this->status->isOK();
 162                 $this->status->merge( $this->manager->unlock( $this->paths, $this->type ) );
 163                 if ( $wasOk ) {
 164                         // Make sure status is OK, despite any unlockFiles() fatals
 165                         $this->status->setResult( true, $this->status->value );
 166                 }
 167         }
 168 }
 169
 170 /**
 171  * Simple version of LockManager that does nothing
 172  * @since 1.19
 173  */
 174 class NullLockManager extends LockManager {
 175         protected function doLock( array $paths, $type ) {
 176                 return Status::newGood();
 177         }
 178
 179         protected function doUnlock( array $paths, $type ) {
 180                 return Status::newGood();
 181         }
 182 }