includes/libs/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  */
  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  */
  33 class 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_integer( $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 &$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         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 }