Make Status extend StatusValue and start FileBackend update

* This avoids code duplication.
* Callers can safely start type-hinting StatusValue as well.
* Also moved the wrap() logic out of Status::__construct(), which
  only wrap() was (and should have been) using. Use "static" as
  well, so subclass behave properly.
* The docs and type-hints in /filebackend are updated as an example.
* A migration pattern is to inject a StatusValue wrapper
  into the backend and use it on all returned statuses, so MediaWiki
  will still get Status for message methods.

Change-Id: Iff9255f34870ea6b0c4b91f6ddc69eea95186aba

7 files changed, 34 insertions, 34 deletions

diff --git a/includes/filebackend/lockmanager/FSLockManager.php b/includes/filebackend/lockmanager/FSLockManager.php
index 2b660ec77e7d..8e149d6380df 100644
--- a/includes/filebackend/lockmanager/FSLockManager.php
+++ b/includes/filebackend/lockmanager/FSLockManager.php
@@ -62,7 +62,7 @@ class FSLockManager extends LockManager {
 	 * @see LockManager::doLock()
 	 * @param array $paths
 	 * @param int $type
-	 * @return Status
+	 * @return StatusValue
 	 */
 	protected function doLock( array $paths, $type ) {
 		$status = Status::newGood();
@@ -87,7 +87,7 @@ class FSLockManager extends LockManager {
 	 * @see LockManager::doUnlock()
 	 * @param array $paths
 	 * @param int $type
-	 * @return Status
+	 * @return StatusValue
 	 */
 	protected function doUnlock( array $paths, $type ) {
 		$status = Status::newGood();
@@ -104,7 +104,7 @@ class FSLockManager extends LockManager {
 	 *
 	 * @param string $path
 	 * @param int $type
-	 * @return Status
+	 * @return StatusValue
 	 */
 	protected function doSingleLock( $path, $type ) {
 		$status = Status::newGood();
@@ -149,7 +149,7 @@ class FSLockManager extends LockManager {
 	 *
 	 * @param string $path
 	 * @param int $type
-	 * @return Status
+	 * @return StatusValue
 	 */
 	protected function doSingleUnlock( $path, $type ) {
 		$status = Status::newGood();
@@ -192,7 +192,7 @@ class FSLockManager extends LockManager {
 	/**
 	 * @param string $path
 	 * @param array $handlesToClose
-	 * @return Status
+	 * @return StatusValue
 	 */
 	private function closeLockHandles( $path, array $handlesToClose ) {
 		$status = Status::newGood();
@@ -210,7 +210,7 @@ class FSLockManager extends LockManager {
 
 	/**
 	 * @param string $path
-	 * @return Status
+	 * @return StatusValue
 	 */
 	private function pruneKeyLockFiles( $path ) {
 		$status = Status::newGood();
diff --git a/includes/filebackend/lockmanager/LockManager.php b/includes/filebackend/lockmanager/LockManager.php
index a3cb3b198656..eff031b58b53 100644
--- a/includes/filebackend/lockmanager/LockManager.php
+++ b/includes/filebackend/lockmanager/LockManager.php
@@ -87,7 +87,7 @@ abstract class LockManager {
 	 * @param array $paths List of resource names
 	 * @param int $type LockManager::LOCK_* constant
 	 * @param int $timeout Timeout in seconds (0 means non-blocking) (since 1.21)
-	 * @return Status
+	 * @return StatusValue
 	 */
 	final public function lock( array $paths, $type = self::LOCK_EX, $timeout = 0 ) {
 		return $this->lockByType( [ $type => $paths ], $timeout );
@@ -98,7 +98,7 @@ abstract class LockManager {
 	 *
 	 * @param array $pathsByType Map of LockManager::LOCK_* constants to lists of paths
 	 * @param int $timeout Timeout in seconds (0 means non-blocking) (since 1.21)
-	 * @return Status
+	 * @return StatusValue
 	 * @since 1.22
 	 */
 	final public function lockByType( array $pathsByType, $timeout = 0 ) {
@@ -123,7 +123,7 @@ abstract class LockManager {
 	 *
 	 * @param array $paths List of paths
 	 * @param int $type LockManager::LOCK_* constant
-	 * @return Status
+	 * @return StatusValue
 	 */
 	final public function unlock( array $paths, $type = self::LOCK_EX ) {
 		return $this->unlockByType( [ $type => $paths ] );
@@ -133,7 +133,7 @@ abstract class LockManager {
 	 * Unlock the resources at the given abstract paths
 	 *
 	 * @param array $pathsByType Map of LockManager::LOCK_* constants to lists of paths
-	 * @return Status
+	 * @return StatusValue
 	 * @since 1.22
 	 */
 	final public function unlockByType( array $pathsByType ) {
@@ -187,7 +187,7 @@ abstract class LockManager {
 	/**
 	 * @see LockManager::lockByType()
 	 * @param array $pathsByType Map of LockManager::LOCK_* constants to lists of paths
-	 * @return Status
+	 * @return StatusValue
 	 * @since 1.22
 	 */
 	protected function doLockByType( array $pathsByType ) {
@@ -214,14 +214,14 @@ abstract class LockManager {
 	 *
 	 * @param array $paths List of paths
 	 * @param int $type LockManager::LOCK_* constant
-	 * @return Status
+	 * @return StatusValue
 	 */
 	abstract protected function doLock( array $paths, $type );
 
 	/**
 	 * @see LockManager::unlockByType()
 	 * @param array $pathsByType Map of LockManager::LOCK_* constants to lists of paths
-	 * @return Status
+	 * @return StatusValue
 	 * @since 1.22
 	 */
 	protected function doUnlockByType( array $pathsByType ) {
@@ -238,7 +238,7 @@ abstract class LockManager {
 	 *
 	 * @param array $paths List of paths
 	 * @param int $type LockManager::LOCK_* constant
-	 * @return Status
+	 * @return StatusValue
 	 */
 	abstract protected function doUnlock( array $paths, $type );
 }
diff --git a/includes/filebackend/lockmanager/MemcLockManager.php b/includes/filebackend/lockmanager/MemcLockManager.php
index 2f17e2722c5a..2e2d0a3533ef 100644
--- a/includes/filebackend/lockmanager/MemcLockManager.php
+++ b/includes/filebackend/lockmanager/MemcLockManager.php
@@ -126,7 +126,7 @@ class MemcLockManager extends QuorumLockManager {
 	 * @param string $lockSrv
 	 * @param array $paths
 	 * @param string $type
-	 * @return Status
+	 * @return StatusValue
 	 */
 	protected function doGetLocksOnServer( $lockSrv, array $paths, $type ) {
 		$status = Status::newGood();
@@ -202,7 +202,7 @@ class MemcLockManager extends QuorumLockManager {
 	 * @param string $lockSrv
 	 * @param array $paths
 	 * @param string $type
-	 * @return Status
+	 * @return StatusValue
 	 */
 	protected function doFreeLocksOnServer( $lockSrv, array $paths, $type ) {
 		$status = Status::newGood();
@@ -254,7 +254,7 @@ class MemcLockManager extends QuorumLockManager {
 
 	/**
 	 * @see QuorumLockManager::releaseAllLocks()
-	 * @return Status
+	 * @return StatusValue
 	 */
 	protected function releaseAllLocks() {
 		return Status::newGood(); // not supported
diff --git a/includes/filebackend/lockmanager/MySqlLockManager.php b/includes/filebackend/lockmanager/MySqlLockManager.php
index 0536091bc437..896e0ffd64f6 100644
--- a/includes/filebackend/lockmanager/MySqlLockManager.php
+++ b/includes/filebackend/lockmanager/MySqlLockManager.php
@@ -35,7 +35,7 @@ class MySqlLockManager extends DBLockManager {
 	 * @param string $lockSrv
 	 * @param array $paths
 	 * @param string $type
-	 * @return Status
+	 * @return StatusValue
 	 */
 	protected function doGetLocksOnServer( $lockSrv, array $paths, $type ) {
 		$status = Status::newGood();
@@ -105,7 +105,7 @@ class MySqlLockManager extends DBLockManager {
 
 	/**
 	 * @see QuorumLockManager::releaseAllLocks()
-	 * @return Status
+	 * @return StatusValue
 	 */
 	protected function releaseAllLocks() {
 		$status = Status::newGood();
diff --git a/includes/filebackend/lockmanager/PostgreSqlLockManager.php b/includes/filebackend/lockmanager/PostgreSqlLockManager.php
index d55b5ae0607e..307c16447ed1 100644
--- a/includes/filebackend/lockmanager/PostgreSqlLockManager.php
+++ b/includes/filebackend/lockmanager/PostgreSqlLockManager.php
@@ -61,7 +61,7 @@ class PostgreSqlLockManager extends DBLockManager {
 
 	/**
 	 * @see QuorumLockManager::releaseAllLocks()
-	 * @return Status
+	 * @return StatusValue
 	 */
 	protected function releaseAllLocks() {
 		$status = Status::newGood();
diff --git a/includes/filebackend/lockmanager/QuorumLockManager.php b/includes/filebackend/lockmanager/QuorumLockManager.php
index 108b8465cf60..0db9e815fe28 100644
--- a/includes/filebackend/lockmanager/QuorumLockManager.php
+++ b/includes/filebackend/lockmanager/QuorumLockManager.php
@@ -124,7 +124,7 @@ abstract class QuorumLockManager extends LockManager {
 	 *
 	 * @param int $bucket
 	 * @param array $pathsByType Map of LockManager::LOCK_* constants to lists of paths
-	 * @return Status
+	 * @return StatusValue
 	 */
 	final protected function doLockingRequestBucket( $bucket, array $pathsByType ) {
 		$status = Status::newGood();
@@ -166,7 +166,7 @@ abstract class QuorumLockManager extends LockManager {
 	 *
 	 * @param int $bucket
 	 * @param array $pathsByType Map of LockManager::LOCK_* constants to lists of paths
-	 * @return Status
+	 * @return StatusValue
 	 */
 	final protected function doUnlockingRequestBucket( $bucket, array $pathsByType ) {
 		$status = Status::newGood();
@@ -189,7 +189,7 @@ abstract class QuorumLockManager extends LockManager {
 				}
 			}
 		}
-		// Set a bad status if the quorum was not met.
+		// Set a bad StatusValue if the quorum was not met.
 		// Assumes the same "up" servers as during the acquire step.
 		$status->setResult( $yesVotes >= $quorum );
 
@@ -222,7 +222,7 @@ abstract class QuorumLockManager extends LockManager {
 	 *
 	 * @param string $lockSrv
 	 * @param array $pathsByType Map of LockManager::LOCK_* constants to lists of paths
-	 * @return Status
+	 * @return StatusValue
 	 */
 	abstract protected function getLocksOnServer( $lockSrv, array $pathsByType );
 
@@ -233,7 +233,7 @@ abstract class QuorumLockManager extends LockManager {
 	 *
 	 * @param string $lockSrv
 	 * @param array $pathsByType Map of LockManager::LOCK_* constants to lists of paths
-	 * @return Status
+	 * @return StatusValue
 	 */
 	abstract protected function freeLocksOnServer( $lockSrv, array $pathsByType );
 
@@ -242,7 +242,7 @@ abstract class QuorumLockManager extends LockManager {
 	 *
 	 * Subclasses must effectively implement this or freeLocksOnServer().
 	 *
-	 * @return Status
+	 * @return StatusValue
 	 */
 	abstract protected function releaseAllLocks();
 }
diff --git a/includes/filebackend/lockmanager/ScopedLock.php b/includes/filebackend/lockmanager/ScopedLock.php
index e1a600ce11ac..05ab289dd687 100644
--- a/includes/filebackend/lockmanager/ScopedLock.php
+++ b/includes/filebackend/lockmanager/ScopedLock.php
@@ -35,7 +35,7 @@ class ScopedLock {
 	/** @var LockManager */
 	protected $manager;
 
-	/** @var Status */
+	/** @var StatusValue */
 	protected $status;
 
 	/** @var array Map of lock types to resource paths */
@@ -44,9 +44,9 @@ class ScopedLock {
 	/**
 	 * @param LockManager $manager
 	 * @param array $pathsByType Map of lock types to path lists
-	 * @param Status $status
+	 * @param StatusValue $status
 	 */
-	protected function __construct( LockManager $manager, array $pathsByType, Status $status ) {
+	protected function __construct( LockManager $manager, array $pathsByType, StatusValue $status ) {
 		$this->manager = $manager;
 		$this->pathsByType = $pathsByType;
 		$this->status = $status;
@@ -55,19 +55,19 @@ class ScopedLock {
 	/**
 	 * Get a ScopedLock object representing a lock on resource paths.
 	 * Any locks are released once this object goes out of scope.
-	 * The status object is updated with any errors or warnings.
+	 * The StatusValue object is updated with any errors or warnings.
 	 *
 	 * @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 StatusValue $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, $timeout = 0
+		LockManager $manager, array $paths, $type, StatusValue $status, $timeout = 0
 	) {
 		$pathsByType = is_integer( $type ) ? [ $type => $paths ] : $paths;
 		$lockStatus = $manager->lockByType( $pathsByType, $timeout );
@@ -80,7 +80,7 @@ class ScopedLock {
 	}
 
 	/**
-	 * Release a scoped lock and set any errors in the attatched Status object.
+	 * Release a scoped lock and set any errors in the attatched StatusValue object.
 	 * This is useful for early release of locks before function scope is destroyed.
 	 * This is the same as setting the lock object to null.
 	 *
@@ -98,7 +98,7 @@ class ScopedLock {
 		$wasOk = $this->status->isOK();
 		$this->status->merge( $this->manager->unlockByType( $this->pathsByType ) );
 		if ( $wasOk ) {
-			// Make sure status is OK, despite any unlockFiles() fatals
+			// Make sure StatusValue is OK, despite any unlockFiles() fatals
 			$this->status->setResult( true, $this->status->value );
 		}
 	}