Update documentation of file backend classes

[lhc/web/wiklou.git] / includes / filebackend / lockmanager / ScopedLock.php

diff --git a/includes/filebackend/lockmanager/ScopedLock.php b/includes/filebackend/lockmanager/ScopedLock.php
index edcb1d6..2056e10 100644 (file)
--- a/includes/filebackend/lockmanager/ScopedLock.php
+++ b/includes/filebackend/lockmanager/ScopedLock.php
@@ -34,26 +34,22 @@
 class ScopedLock {
        /** @var LockManager */
        protected $manager;
+
        /** @var Status */
        protected $status;
-       /** @var Array List of resource paths*/
-       protected $paths;
 
-       protected $type; // integer lock type
+       /** @var array Map of lock types to resource paths */
+       protected $pathsByType;
 
        /**
-        * @param $manager LockManager
-        * @param array $paths List of storage paths
-        * @param $type integer LockManager::LOCK_* constant
-        * @param $status Status
+        * @param LockManager $manager
+        * @param array $pathsByType Map of lock types to path lists
+        * @param Status $status
         */
-       protected function __construct(
-               LockManager $manager, array $paths, $type, Status $status
-       ) {
+       protected function __construct( LockManager $manager, array $pathsByType, Status $status ) {
                $this->manager = $manager;
-               $this->paths = $paths;
+               $this->pathsByType = $pathsByType;
                $this->status = $status;
-               $this->type = $type;
        }
 
        /**
@@ -61,20 +57,25 @@ class ScopedLock {
         * Any locks are released once this object goes out of scope.
         * The status object is updated with any errors or warnings.
         *
-        * @param $manager LockManager
-        * @param array $paths List of storage paths
-        * @param $type integer LockManager::LOCK_* constant
-        * @param $status Status
+        * @param LockManager $manager
+        * @param array $paths List of storage paths or map of lock types to path lists
+        * @param int|string $type LockManager::LOCK_* constant or "mixed" and $paths
+        *   can be a map of types to paths (since 1.22). Otherwise $type should be an
+        *   integer and $paths should be a list of paths.
+        * @param Status $status
+        * @param int $timeout Timeout in seconds (0 means non-blocking) (since 1.22)
         * @return ScopedLock|null Returns null on failure
         */
        public static function factory(
-               LockManager $manager, array $paths, $type, Status $status
+               LockManager $manager, array $paths, $type, Status $status, $timeout = 0
        ) {
-               $lockStatus = $manager->lock( $paths, $type );
+               $pathsByType = is_integer( $type ) ? array( $type => $paths ) : $paths;
+               $lockStatus = $manager->lockByType( $pathsByType, $timeout );
                $status->merge( $lockStatus );
                if ( $lockStatus->isOK() ) {
-                       return new self( $manager, $paths, $type, $status );
+                       return new self( $manager, $pathsByType, $status );
                }
+
                return null;
        }
 
@@ -84,16 +85,18 @@ class ScopedLock {
         * This is the same as setting the lock object to null.
         *
         * @param ScopedLock $lock
-        * @return void
         * @since 1.21
         */
        public static function release( ScopedLock &$lock = null ) {
                $lock = null;
        }
 
+       /**
+        * Release the locks when this goes out of scope
+        */
        function __destruct() {
                $wasOk = $this->status->isOK();
-               $this->status->merge( $this->manager->unlock( $this->paths, $this->type ) );
+               $this->status->merge( $this->manager->unlockByType( $this->pathsByType ) );
                if ( $wasOk ) {
                        // Make sure status is OK, despite any unlockFiles() fatals
                        $this->status->setResult( true, $this->status->value );