1<?php 2/** 3 * Resource locking handling. 4 * 5 * This program is free software; you can redistribute it and/or modify 6 * it under the terms of the GNU General Public License as published by 7 * the Free Software Foundation; either version 2 of the License, or 8 * (at your option) any later version. 9 * 10 * This program is distributed in the hope that it will be useful, 11 * but WITHOUT ANY WARRANTY; without even the implied warranty of 12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 13 * GNU General Public License for more details. 14 * 15 * You should have received a copy of the GNU General Public License along 16 * with this program; if not, write to the Free Software Foundation, Inc., 17 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. 18 * http://www.gnu.org/copyleft/gpl.html 19 * 20 * @file 21 * @ingroup LockManager 22 */ 23 24/** 25 * Self-releasing locks 26 * 27 * LockManager helper class to handle scoped locks, which 28 * release when an object is destroyed or goes out of scope. 29 * 30 * @ingroup LockManager 31 * @since 1.19 32 */ 33class ScopedLock { 34 /** @var LockManager */ 35 protected $manager; 36 37 /** @var StatusValue */ 38 protected $status; 39 40 /** @var array Map of lock types to resource paths */ 41 protected $pathsByType; 42 43 /** 44 * @param LockManager $manager 45 * @param array $pathsByType Map of lock types to path lists 46 * @param StatusValue $status 47 */ 48 protected function __construct( 49 LockManager $manager, array $pathsByType, StatusValue $status 50 ) { 51 $this->manager = $manager; 52 $this->pathsByType = $pathsByType; 53 $this->status = $status; 54 } 55 56 /** 57 * Get a ScopedLock object representing a lock on resource paths. 58 * Any locks are released once this object goes out of scope. 59 * The StatusValue object is updated with any errors or warnings. 60 * 61 * @param LockManager $manager 62 * @param array $paths List of storage paths or map of lock types to path lists 63 * @param int|string $type LockManager::LOCK_* constant or "mixed" and $paths 64 * can be a map of types to paths (since 1.22). Otherwise $type should be an 65 * integer and $paths should be a list of paths. 66 * @param StatusValue $status 67 * @param int $timeout Timeout in seconds (0 means non-blocking) (since 1.22) 68 * @return ScopedLock|null Returns null on failure 69 */ 70 public static function factory( 71 LockManager $manager, array $paths, $type, StatusValue $status, $timeout = 0 72 ) { 73 $pathsByType = is_int( $type ) ? [ $type => $paths ] : $paths; 74 $lockStatus = $manager->lockByType( $pathsByType, $timeout ); 75 $status->merge( $lockStatus ); 76 if ( $lockStatus->isOK() ) { 77 return new self( $manager, $pathsByType, $status ); 78 } 79 80 return null; 81 } 82 83 /** 84 * Release a scoped lock and set any errors in the attatched StatusValue object. 85 * This is useful for early release of locks before function scope is destroyed. 86 * This is the same as setting the lock object to null. 87 * 88 * @param ScopedLock|null &$lock 89 * @since 1.21 90 */ 91 public static function release( ScopedLock &$lock = null ) { 92 $lock = null; 93 } 94 95 /** 96 * Release the locks when this goes out of scope 97 */ 98 public function __destruct() { 99 $wasOk = $this->status->isOK(); 100 $this->status->merge( $this->manager->unlockByType( $this->pathsByType ) ); 101 if ( $wasOk ) { 102 // Make sure StatusValue is OK, despite any unlockFiles() fatals 103 $this->status->setResult( true, $this->status->value ); 104 } 105 } 106} 107