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