includes/filebackend/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         protected $domain; // string; domain (usually wiki ID)
  57
  58         /* Lock types; stronger locks have higher values */
  59         const LOCK_SH = 1; // shared lock (for reads)
  60         const LOCK_UW = 2; // shared lock (for reads used to write elsewhere)
  61         const LOCK_EX = 3; // exclusive lock (for writes)
  62
  63         /**
  64          * Construct a new instance from configuration
  65          *
  66          * $config paramaters include:
  67          *   - domain : Domain (usually wiki ID) that all resources are relative to [optional]
  68          *
  69          * @param $config Array
  70          */
  71         public function __construct( array $config ) {
  72                 $this->domain = isset( $config['domain'] ) ? $config['domain'] : wfWikiID();
  73         }
  74
  75         /**
  76          * Lock the resources at the given abstract paths
  77          *
  78          * @param $paths Array List of resource names
  79          * @param $type integer LockManager::LOCK_* constant
  80          * @return Status
  81          */
  82         final public function lock( array $paths, $type = self::LOCK_EX ) {
  83                 wfProfileIn( __METHOD__ );
  84                 $status = $this->doLock( array_unique( $paths ), $this->lockTypeMap[$type] );
  85                 wfProfileOut( __METHOD__ );
  86                 return $status;
  87         }
  88
  89         /**
  90          * Unlock the resources at the given abstract paths
  91          *
  92          * @param $paths Array List of storage paths
  93          * @param $type integer LockManager::LOCK_* constant
  94          * @return Status
  95          */
  96         final public function unlock( array $paths, $type = self::LOCK_EX ) {
  97                 wfProfileIn( __METHOD__ );
  98                 $status = $this->doUnlock( array_unique( $paths ), $this->lockTypeMap[$type] );
  99                 wfProfileOut( __METHOD__ );
 100                 return $status;
 101         }
 102
 103         /**
 104          * Get the base 36 SHA-1 of a string, padded to 31 digits.
 105          * Before hashing, the path will be prefixed with the domain ID.
 106          * This should be used interally for lock key or file names.
 107          *
 108          * @param $path string
 109          * @return string
 110          */
 111         final protected function sha1Base36Absolute( $path ) {
 112                 return wfBaseConvert( sha1( "{$this->domain}:{$path}" ), 16, 36, 31 );
 113         }
 114
 115         /**
 116          * Get the base 16 SHA-1 of a string, padded to 31 digits.
 117          * Before hashing, the path will be prefixed with the domain ID.
 118          * This should be used interally for lock key or file names.
 119          *
 120          * @param $path string
 121          * @return string
 122          */
 123         final protected function sha1Base16Absolute( $path ) {
 124                 return sha1( "{$this->domain}:{$path}" );
 125         }
 126
 127         /**
 128          * Lock resources with the given keys and lock type
 129          *
 130          * @param $paths Array List of storage paths
 131          * @param $type integer LockManager::LOCK_* constant
 132          * @return string
 133          */
 134         abstract protected function doLock( array $paths, $type );
 135
 136         /**
 137          * Unlock resources with the given keys and lock type
 138          *
 139          * @param $paths Array List of storage paths
 140          * @param $type integer LockManager::LOCK_* constant
 141          * @return string
 142          */
 143         abstract protected function doUnlock( array $paths, $type );
 144 }
 145
 146 /**
 147  * Simple version of LockManager that does nothing
 148  * @since 1.19
 149  */
 150 class NullLockManager extends LockManager {
 151         /**
 152          * @see LockManager::doLock()
 153          * @param $paths array
 154          * @param $type int
 155          * @return Status
 156          */
 157         protected function doLock( array $paths, $type ) {
 158                 return Status::newGood();
 159         }
 160
 161         /**
 162          * @see LockManager::doUnlock()
 163          * @param $paths array
 164          * @param $type int
 165          * @return Status
 166          */
 167         protected function doUnlock( array $paths, $type ) {
 168                 return Status::newGood();
 169         }
 170 }