[Summary view] [Print] [Text view]

   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  
  38      /** @var Status */
  39      protected $status;
  40  
  41      /** @var array Map of lock types to resource paths */
  42      protected $pathsByType;
  43  
  44      /**
  45       * @param LockManager $manager
  46       * @param array $pathsByType Map of lock types to path lists
  47       * @param Status $status
  48       */
  49  	protected function __construct( LockManager $manager, array $pathsByType, Status $status ) {
  50          $this->manager = $manager;
  51          $this->pathsByType = $pathsByType;
  52          $this->status = $status;
  53      }
  54  
  55      /**
  56       * Get a ScopedLock object representing a lock on resource paths.
  57       * Any locks are released once this object goes out of scope.
  58       * The status object is updated with any errors or warnings.
  59       *
  60       * @param LockManager $manager
  61       * @param array $paths List of storage paths or map of lock types to path lists
  62       * @param int|string $type LockManager::LOCK_* constant or "mixed" and $paths
  63       *   can be a map of types to paths (since 1.22). Otherwise $type should be an
  64       *   integer and $paths should be a list of paths.
  65       * @param Status $status
  66       * @param int $timeout Timeout in seconds (0 means non-blocking) (since 1.22)
  67       * @return ScopedLock|null Returns null on failure
  68       */
  69  	public static function factory(
  70          LockManager $manager, array $paths, $type, Status $status, $timeout = 0
  71      ) {
  72          $pathsByType = is_integer( $type ) ? array( $type => $paths ) : $paths;
  73          $lockStatus = $manager->lockByType( $pathsByType, $timeout );
  74          $status->merge( $lockStatus );
  75          if ( $lockStatus->isOK() ) {
  76              return new self( $manager, $pathsByType, $status );
  77          }
  78  
  79          return null;
  80      }
  81  
  82      /**
  83       * Release a scoped lock and set any errors in the attatched Status object.
  84       * This is useful for early release of locks before function scope is destroyed.
  85       * This is the same as setting the lock object to null.
  86       *
  87       * @param ScopedLock $lock
  88       * @since 1.21
  89       */
  90  	public static function release( ScopedLock &$lock = null ) {
  91          $lock = null;
  92      }
  93  
  94      /**
  95       * Release the locks when this goes out of scope
  96       */
  97  	function __destruct() {
  98          $wasOk = $this->status->isOK();
  99          $this->status->merge( $this->manager->unlockByType( $this->pathsByType ) );
 100          if ( $wasOk ) {
 101              // Make sure status is OK, despite any unlockFiles() fatals
 102              $this->status->setResult( true, $this->status->value );
 103          }
 104      }
 105  }