includes/filerepo/backend/lockmanager/LockManager.php

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