includes/filebackend/lockmanager/ScopedLock.php

   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  * @author Aaron Schulz
  23  */
  24
  25 /**
  26  * Self-releasing locks
  27  *
  28  * LockManager helper class to handle scoped locks, which
  29  * release when an object is destroyed or goes out of scope.
  30  *
  31  * @ingroup LockManager
  32  * @since 1.19
  33  */
  34 class ScopedLock {
  35         /** @var LockManager */
  36         protected $manager;
  37         /** @var Status */
  38         protected $status;
  39         /** @var Array List of resource paths*/
  40         protected $paths;
  41
  42         protected $type; // integer lock type
  43
  44         /**
  45          * @param $manager LockManager
  46          * @param array $paths List of storage paths
  47          * @param $type integer LockManager::LOCK_* constant
  48          * @param $status Status
  49          */
  50         protected function __construct(
  51                 LockManager $manager, array $paths, $type, Status $status
  52         ) {
  53                 $this->manager = $manager;
  54                 $this->paths = $paths;
  55                 $this->status = $status;
  56                 $this->type = $type;
  57         }
  58
  59         /**
  60          * Get a ScopedLock object representing a lock on resource paths.
  61          * Any locks are released once this object goes out of scope.
  62          * The status object is updated with any errors or warnings.
  63          *
  64          * @param $manager LockManager
  65          * @param array $paths List of storage paths
  66          * @param $type integer LockManager::LOCK_* constant
  67          * @param $status Status
  68          * @return ScopedLock|null Returns null on failure
  69          */
  70         public static function factory(
  71                 LockManager $manager, array $paths, $type, Status $status
  72         ) {
  73                 $lockStatus = $manager->lock( $paths, $type );
  74                 $status->merge( $lockStatus );
  75                 if ( $lockStatus->isOK() ) {
  76                         return new self( $manager, $paths, $type, $status );
  77                 }
  78                 return null;
  79         }
  80
  81         /**
  82          * Release a scoped lock and set any errors in the attatched Status object.
  83          * This is useful for early release of locks before function scope is destroyed.
  84          * This is the same as setting the lock object to null.
  85          *
  86          * @param ScopedLock $lock
  87          * @return void
  88          * @since 1.21
  89          */
  90         public static function release( ScopedLock &$lock = null ) {
  91                 $lock = null;
  92         }
  93
  94         function __destruct() {
  95                 $wasOk = $this->status->isOK();
  96                 $this->status->merge( $this->manager->unlock( $this->paths, $this->type ) );
  97                 if ( $wasOk ) {
  98                         // Make sure status is OK, despite any unlockFiles() fatals
  99                         $this->status->setResult( true, $this->status->value );
 100                 }
 101         }
 102 }