From: Aaron Schulz <aaron@users.mediawiki.org>
Date: Fri, 23 Dec 2011 09:43:28 +0000 (+0000)
Subject: * Added 'latest' parameter to functions that get information about a file. This will... 
X-Git-Tag: 1.31.0-rc.0~25791
X-Git-Url: https://git.cyclocoop.org/?a=commitdiff_plain;ds=sidebyside;h=31a9b1be0043f7587c5bd67e0ee13af3f31febd1;p=lhc%2Fweb%2Fwiklou.git

* Added 'latest' parameter to functions that get information about a file. This will get the latest version among all storage nodes. Non-distributed backends can ignore this.
* In doOperations(), ignore 'nonLocking' unless 'ignoreErrors' is set. Split out a doOperationsInternal() function so the sanity check could go in doOperations().
* Moved getFileList() down a bit.
* Documentation tweaks.
---

diff --git a/includes/filerepo/backend/FileBackend.php b/includes/filerepo/backend/FileBackend.php
index 3a81b6448a..f6b2a697b6 100644
--- a/includes/filerepo/backend/FileBackend.php
+++ b/includes/filerepo/backend/FileBackend.php
@@ -128,11 +128,15 @@ abstract class FileBackendBase {
 	 *                         exists at the destination that has the same
 	 *                         contents as the new contents to be written there.
 	 * 
-	 * $opts is an associative of options, including:
+	 * $opts is an associative of boolean flags, including:
+	 * 'ignoreErrors'        : Errors that would normally cause a rollback do not.
+	 *                         The remaining operations are still attempted if any fail.
 	 * 'nonLocking'          : No locks are acquired for the operations.
 	 *                         This can increase performance for non-critical writes.
-	 * 'ignoreErrors'        : Serious errors that would normally cause a rollback
-	 *                         do not. The remaining operations are still attempted.
+	 *                         This has no effect unless the 'ignoreErrors' flag is set.
+	 * 'allowStale'          : Don't require the latest available data.
+	 *                         This can increase performance for non-critical writes.
+	 *                         This has no effect unless the 'ignoreErrors' flag is set.
 	 * 
 	 * Return value:
 	 * This returns a Status, which contains all warnings and fatals that occured
@@ -144,7 +148,18 @@ abstract class FileBackendBase {
 	 * @param $opts Array Batch operation options
 	 * @return Status
 	 */
-	abstract public function doOperations( array $ops, array $opts = array() );
+	final public function doOperations( array $ops, array $opts = array() ) {
+		if ( empty( $opts['ignoreErrors'] ) ) { // sanity
+			unset( $opts['nonLocking'] );
+			unset( $opts['allowStale'] );
+		}
+		return $this->doOperationsInternal( $ops, $opts );
+	}
+
+	/**
+	 * @see FileBackendBase::doOperations()
+	 */
+	abstract protected function doOperationsInternal( array $ops, array $opts );
 
 	/**
 	 * Same as doOperations() except it takes a single operation.
@@ -296,7 +311,8 @@ abstract class FileBackendBase {
 	 * Check if a file exists at a storage path in the backend.
 	 * 
 	 * $params include:
-	 *     src : source storage path
+	 *     src    : source storage path
+	 *     latest : use the latest available data
 	 * 
 	 * @param $params Array
 	 * @return bool
@@ -307,7 +323,8 @@ abstract class FileBackendBase {
 	 * Get a SHA-1 hash of the file at a storage path in the backend.
 	 * 
 	 * $params include:
-	 *     src : source storage path
+	 *     src    : source storage path
+	 *     latest : use the latest available data
 	 * 
 	 * @param $params Array
 	 * @return string|false Hash string or false on failure
@@ -318,7 +335,8 @@ abstract class FileBackendBase {
 	 * Get the last-modified timestamp of the file at a storage path.
 	 * 
 	 * $params include:
-	 *     src : source storage path
+	 *     src    : source storage path
+	 *     latest : use the latest available data
 	 * 
 	 * @param $params Array
 	 * @return string|false TS_MW timestamp or false on failure
@@ -330,7 +348,8 @@ abstract class FileBackendBase {
 	 * Returns FSFile::placeholderProps() on failure.
 	 * 
 	 * $params include:
-	 *     src : source storage path
+	 *     src    : source storage path
+	 *     latest : use the latest available data
 	 * 
 	 * @param $params Array
 	 * @return Array
@@ -346,26 +365,13 @@ abstract class FileBackendBase {
 	 * $params include:
 	 *     src     : source storage path
 	 *     headers : additional HTTP headers to send on success
+	 *     latest  : use the latest available data
 	 * 
 	 * @param $params Array
 	 * @return Status
 	 */
 	abstract public function streamFile( array $params );
 
-	/**
-	 * Get an iterator to list out all object files under a storage directory.
-	 * If the directory is of the form "mwstore://container", then all items in
-	 * the container should be listed. If of the form "mwstore://container/dir",
-	 * then all items under that container directory should be listed.
-	 * Results should be storage paths relative to the given directory.
-	 * 
-	 * $params include:
-	 *     dir : storage path directory
-	 *
-	 * @return Traversable|Array|null Returns null on failure
-	 */
-	abstract public function getFileList( array $params );
-
 	/**
 	 * Returns a file system file, identical to the file at a storage path.
 	 * The file returned is either:
@@ -379,7 +385,8 @@ abstract class FileBackendBase {
 	 * In that later case, there are copies of the file that must stay in sync.
 	 * 
 	 * $params include:
-	 *     src : source storage path
+	 *     src    : source storage path
+	 *     latest : use the latest available data
 	 * 
 	 * @param $params Array
 	 * @return FSFile|null Returns null on failure
@@ -392,13 +399,28 @@ abstract class FileBackendBase {
 	 * Temporary files may be purged when the file object falls out of scope.
 	 * 
 	 * $params include:
-	 *     src : source storage path
+	 *     src    : source storage path
+	 *     latest : use the latest available data
 	 * 
 	 * @param $params Array
 	 * @return TempFSFile|null Returns null on failure
 	 */
 	abstract public function getLocalCopy( array $params );
 
+	/**
+	 * Get an iterator to list out all object files under a storage directory.
+	 * If the directory is of the form "mwstore://container", then all items in
+	 * the container should be listed. If of the form "mwstore://container/dir",
+	 * then all items under that container directory should be listed.
+	 * Results should be storage paths relative to the given directory.
+	 * 
+	 * $params include:
+	 *     dir : storage path directory
+	 *
+	 * @return Traversable|Array|null Returns null on failure
+	 */
+	abstract public function getFileList( array $params );
+
 	/**
 	 * Lock the files at the given storage paths in the backend.
 	 * This will either lock all the files or none (on failure).
@@ -700,6 +722,8 @@ abstract class FileBackend extends FileBackendBase {
 
 	/**
 	 * Return a list of FileOp objects from a list of operations.
+	 * Do not call this function from places outside FileBackend.
+	 *
 	 * The result must have the same number of items as the input.
 	 * An exception is thrown if an unsupported operation is requested.
 	 * 
@@ -729,14 +753,15 @@ abstract class FileBackend extends FileBackendBase {
 	}
 
 	/**
-	 * @see FileBackendBase::doOperations()
+	 * @see FileBackendBase::doOperationsInternal()
 	 */
-	final public function doOperations( array $ops, array $opts = array() ) {
+	protected function doOperationsInternal( array $ops, array $opts ) {
 		$status = Status::newGood();
 
 		// Build up a list of FileOps...
 		$performOps = $this->getOperations( $ops );
 
+		// Acquire any locks as needed...
 		if ( empty( $opts['nonLocking'] ) ) {
 			// Build up a list of files to lock...
 			$filesLockEx = $filesLockSh = array();
diff --git a/includes/filerepo/backend/FileBackendMultiWrite.php b/includes/filerepo/backend/FileBackendMultiWrite.php
index c73dcca454..d9b90c2cb6 100644
--- a/includes/filerepo/backend/FileBackendMultiWrite.php
+++ b/includes/filerepo/backend/FileBackendMultiWrite.php
@@ -10,6 +10,8 @@
  * registered to this proxy backend and it will act as a single backend.
  * Use this when all access to those backends is through this proxy backend.
  * At least one of the backends must be declared the "master" backend.
+ *
+ * Only use this class when transitioning from one storage system to another.
  * 
  * The order that the backends are defined sets the priority of which
  * backend is read from or written to first. Functions like fileExists()
@@ -62,7 +64,10 @@ class FileBackendMultiWrite extends FileBackendBase {
 		}
 	}
 
-	final public function doOperations( array $ops, array $opts = array() ) {
+	/**
+	 * @see FileBackendBase::doOperationsInternal()
+	 */
+	final protected function doOperationsInternal( array $ops, array $opts ) {
 		$status = Status::newGood();
 
 		$performOps = array(); // list of FileOp objects
@@ -145,6 +150,9 @@ class FileBackendMultiWrite extends FileBackendBase {
 		}
 	}
 
+	/**
+	 * @see FileBackendBase::prepare()
+	 */
 	function prepare( array $params ) {
 		$status = Status::newGood();
 		foreach ( $this->backends as $backend ) {
@@ -154,6 +162,9 @@ class FileBackendMultiWrite extends FileBackendBase {
 		return $status;
 	}
 
+	/**
+	 * @see FileBackendBase::secure()
+	 */
 	function secure( array $params ) {
 		$status = Status::newGood();
 		foreach ( $this->backends as $backend ) {
@@ -163,6 +174,9 @@ class FileBackendMultiWrite extends FileBackendBase {
 		return $status;
 	}
 
+	/**
+	 * @see FileBackendBase::clean()
+	 */
 	function clean( array $params ) {
 		$status = Status::newGood();
 		foreach ( $this->backends as $backend ) {
@@ -172,6 +186,9 @@ class FileBackendMultiWrite extends FileBackendBase {
 		return $status;
 	}
 
+	/**
+	 * @see FileBackendBase::fileExists()
+	 */
 	function fileExists( array $params ) {
 		# Hit all backends in case of failed operations (out of sync)
 		foreach ( $this->backends as $backend ) {
@@ -183,12 +200,18 @@ class FileBackendMultiWrite extends FileBackendBase {
 		return false;
 	}
 
+	/**
+	 * @see FileBackendBase::getFileTimestamp()
+	 */
 	function getFileTimestamp( array $params ) {
 		// Skip non-master for consistent timestamps
 		$realParams = $this->substOpPaths( $params, $backend );
 		return $this->backends[$this->masterIndex]->getFileTimestamp( $realParams );
 	}
 
+	/**
+	 * @see FileBackendBase::getFileSha1Base36()
+	 */
 	function getFileSha1Base36( array $params ) {
 		# Hit all backends in case of failed operations (out of sync)
 		foreach ( $this->backends as $backend ) {
@@ -201,6 +224,9 @@ class FileBackendMultiWrite extends FileBackendBase {
 		return false;
 	}
 
+	/**
+	 * @see FileBackendBase::getFileProps()
+	 */
 	function getFileProps( array $params ) {
 		# Hit all backends in case of failed operations (out of sync)
 		foreach ( $this->backends as $backend ) {
@@ -213,6 +239,9 @@ class FileBackendMultiWrite extends FileBackendBase {
 		return null;
 	}
 
+	/**
+	 * @see FileBackendBase::streamFile()
+	 */
 	function streamFile( array $params ) {
 		$status = Status::newGood();
 		foreach ( $this->backends as $backend ) {
@@ -234,6 +263,9 @@ class FileBackendMultiWrite extends FileBackendBase {
 		return $status;
 	}
 
+	/**
+	 * @see FileBackendBase::getLocalReference()
+	 */
 	function getLocalReference( array $params ) {
 		# Hit all backends in case of failed operations (out of sync)
 		foreach ( $this->backends as $backend ) {
@@ -246,6 +278,9 @@ class FileBackendMultiWrite extends FileBackendBase {
 		return null;
 	}
 
+	/**
+	 * @see FileBackendBase::getLocalCopy()
+	 */
 	function getLocalCopy( array $params ) {
 		# Hit all backends in case of failed operations (out of sync)
 		foreach ( $this->backends as $backend ) {
@@ -258,6 +293,9 @@ class FileBackendMultiWrite extends FileBackendBase {
 		return null;
 	}
 
+	/**
+	 * @see FileBackendBase::getFileList()
+	 */
 	function getFileList( array $params ) {
 		foreach ( $this->backends as $index => $backend ) {
 			# Get results from the first backend