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  * @brief 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                 wfProfileIn( __METHOD__ );
  60                 $status = $this->doLock( array_unique( $paths ), $this->lockTypeMap[$type] );
  61                 wfProfileOut( __METHOD__ );
  62                 return $status;
  63         }
  64
  65         /**
  66          * Unlock the resources at the given abstract paths
  67          *
  68          * @param $paths Array List of storage paths
  69          * @param $type integer LockManager::LOCK_* constant
  70          * @return Status
  71          */
  72         final public function unlock( array $paths, $type = self::LOCK_EX ) {
  73                 wfProfileIn( __METHOD__ );
  74                 $status = $this->doUnlock( array_unique( $paths ), $this->lockTypeMap[$type] );
  75                 wfProfileOut( __METHOD__ );
  76                 return $status;
  77         }
  78
  79         /**
  80          * Get the base 36 SHA-1 of a string, padded to 31 digits
  81          *
  82          * @param $path string
  83          * @return string
  84          */
  85         final protected static function sha1Base36( $path ) {
  86                 return wfBaseConvert( sha1( $path ), 16, 36, 31 );
  87         }
  88
  89         /**
  90          * Lock resources with the given keys and lock type
  91          *
  92          * @param $paths Array List of storage paths
  93          * @param $type integer LockManager::LOCK_* constant
  94          * @return string
  95          */
  96         abstract protected function doLock( array $paths, $type );
  97
  98         /**
  99          * Unlock resources with the given keys and lock type
 100          *
 101          * @param $paths Array List of storage paths
 102          * @param $type integer LockManager::LOCK_* constant
 103          * @return string
 104          */
 105         abstract protected function doUnlock( array $paths, $type );
 106 }
 107
 108 /**
 109  * Self releasing locks
 110  *
 111  * LockManager helper class to handle scoped locks, which
 112  * release when an object is destroyed or goes out of scope.
 113  *
 114  * @ingroup LockManager
 115  * @since 1.19
 116  */
 117 class ScopedLock {
 118         /** @var LockManager */
 119         protected $manager;
 120         /** @var Status */
 121         protected $status;
 122         /** @var Array List of resource paths*/
 123         protected $paths;
 124
 125         protected $type; // integer lock type
 126
 127         /**
 128          * @param $manager LockManager
 129          * @param $paths Array List of storage paths
 130          * @param $type integer LockManager::LOCK_* constant
 131          * @param $status Status
 132          */
 133         protected function __construct(
 134                 LockManager $manager, array $paths, $type, Status $status
 135         ) {
 136                 $this->manager = $manager;
 137                 $this->paths = $paths;
 138                 $this->status = $status;
 139                 $this->type = $type;
 140         }
 141
 142         protected function __clone() {}
 143
 144         /**
 145          * Get a ScopedLock object representing a lock on resource paths.
 146          * Any locks are released once this object goes out of scope.
 147          * The status object is updated with any errors or warnings.
 148          *
 149          * @param $manager LockManager
 150          * @param $paths Array List of storage paths
 151          * @param $type integer LockManager::LOCK_* constant
 152          * @param $status Status
 153          * @return ScopedLock|null Returns null on failure
 154          */
 155         public static function factory(
 156                 LockManager $manager, array $paths, $type, Status $status
 157         ) {
 158                 $lockStatus = $manager->lock( $paths, $type );
 159                 $status->merge( $lockStatus );
 160                 if ( $lockStatus->isOK() ) {
 161                         return new self( $manager, $paths, $type, $status );
 162                 }
 163                 return null;
 164         }
 165
 166         function __destruct() {
 167                 $wasOk = $this->status->isOK();
 168                 $this->status->merge( $this->manager->unlock( $this->paths, $this->type ) );
 169                 if ( $wasOk ) {
 170                         // Make sure status is OK, despite any unlockFiles() fatals
 171                         $this->status->setResult( true, $this->status->value );
 172                 }
 173         }
 174 }
 175
 176 /**
 177  * Simple version of LockManager that does nothing
 178  * @since 1.19
 179  */
 180 class NullLockManager extends LockManager {
 181         /**
 182          * @see LockManager::doLock()
 183          * @return Status
 184          */
 185         protected function doLock( array $paths, $type ) {
 186                 return Status::newGood();
 187         }
 188
 189         /**
 190          * @see LockManager::doUnlock()
 191          * @return Status
 192          */
 193         protected function doUnlock( array $paths, $type ) {
 194                 return Status::newGood();
 195         }
 196 }