From 34a4bcbd48bf7af458eb110cc383c5bbb6989a31 Mon Sep 17 00:00:00 2001 From: Siebrand Mazeland Date: Sat, 23 Nov 2013 19:23:32 +0100 Subject: [PATCH] Update documentation of file backend classes Change-Id: I2113aecc53f1b361d9c276113bc0a9f7076cd21c --- includes/filebackend/FSFile.php | 13 +- includes/filebackend/FSFileBackend.php | 65 +++++--- includes/filebackend/FileBackend.php | 120 ++++++-------- includes/filebackend/FileBackendGroup.php | 15 +- .../filebackend/FileBackendMultiWrite.php | 36 +++-- includes/filebackend/FileBackendStore.php | 86 ++++++---- includes/filebackend/FileOp.php | 66 +++++--- includes/filebackend/FileOpBatch.php | 2 +- includes/filebackend/SwiftFileBackend.php | 153 ++++++++++++------ includes/filebackend/TempFSFile.php | 5 +- .../filebackend/filejournal/DBFileJournal.php | 18 ++- .../filebackend/filejournal/FileJournal.php | 63 ++++---- .../filebackend/lockmanager/DBLockManager.php | 31 ++-- .../filebackend/lockmanager/FSLockManager.php | 32 ++-- .../filebackend/lockmanager/LSLockManager.php | 27 ++-- .../filebackend/lockmanager/LockManager.php | 32 ++-- .../lockmanager/LockManagerGroup.php | 19 +-- .../lockmanager/MemcLockManager.php | 40 +++-- .../lockmanager/QuorumLockManager.php | 19 +-- .../lockmanager/RedisLockManager.php | 16 +- .../filebackend/lockmanager/ScopedLock.php | 14 +- 21 files changed, 487 insertions(+), 385 deletions(-) diff --git a/includes/filebackend/FSFile.php b/includes/filebackend/FSFile.php index 97ce593114..3a0aa9747d 100644 --- a/includes/filebackend/FSFile.php +++ b/includes/filebackend/FSFile.php @@ -27,8 +27,11 @@ * @ingroup FileBackend */ class FSFile { - protected $path; // path to file - protected $sha1Base36; // file SHA-1 in base 36 + /** @var string Path to file */ + protected $path; + + /** @var string File SHA-1 in base 36 */ + protected $sha1Base36; /** * Sets up the file object @@ -155,7 +158,7 @@ class FSFile { /** * Placeholder file properties to use for files that don't exist * - * @return Array + * @return array */ public static function placeholderProps() { $info = array(); @@ -175,7 +178,7 @@ class FSFile { * Exract image size information * * @param array $gis - * @return Array + * @return array */ protected function extractImageSizeInfo( array $gis ) { $info = array(); @@ -240,7 +243,7 @@ class FSFile { * * @param string $path absolute local filesystem path * @param mixed $ext The file extension, or true to extract it from the filename. - * Set it to false to ignore the extension. + * Set it to false to ignore the extension. * @return array */ public static function getPropsFromPath( $path, $ext = true ) { diff --git a/includes/filebackend/FSFileBackend.php b/includes/filebackend/FSFileBackend.php index cacae9b3a7..993e2bac49 100644 --- a/includes/filebackend/FSFileBackend.php +++ b/includes/filebackend/FSFileBackend.php @@ -39,14 +39,22 @@ * @since 1.19 */ class FSFileBackend extends FileBackendStore { - protected $basePath; // string; directory holding the container directories - /** @var Array Map of container names to root paths */ - protected $containerPaths = array(); // for custom container paths - protected $fileMode; // integer; file permission mode - protected $fileOwner; // string; required OS username to own files - protected $currentUser; // string; OS username running this script - - /** @var Array */ + /** @var string Directory holding the container directories */ + protected $basePath; + + /** @var array Map of container names to root paths for custom container paths */ + protected $containerPaths = array(); + + /** @var int File permission mode */ + protected $fileMode; + + /** @var string Required OS username to own files */ + protected $fileOwner; + + /** @var string OS username running this script */ + protected $currentUser; + + /** @var array */ protected $hadWarningErrors = array(); /** @@ -444,6 +452,12 @@ class FSFileBackend extends FileBackendStore { } } + /** + * @param string $fullCont + * @param $dirRel + * @param array $params + * @return Status + */ protected function doPrepareInternal( $fullCont, $dirRel, array $params ) { $status = Status::newGood(); list( , $shortCont, ) = FileBackend::splitStoragePath( $params['dir'] ); @@ -581,7 +595,10 @@ class FSFileBackend extends FileBackendStore { /** * @see FileBackendStore::getDirectoryListInternal() - * @return Array|null + * @param string $fullCont + * @param string $dirRel + * @param array $params + * @return array|null */ public function getDirectoryListInternal( $fullCont, $dirRel, array $params ) { list( , $shortCont, ) = FileBackend::splitStoragePath( $params['dir'] ); @@ -603,7 +620,10 @@ class FSFileBackend extends FileBackendStore { /** * @see FileBackendStore::getFileListInternal() - * @return Array|FSFileBackendFileList|null + * @param string $fullCont + * @param string $dirRel + * @param array $params + * @return array|FSFileBackendFileList|null */ public function getFileListInternal( $fullCont, $dirRel, array $params ) { list( , $shortCont, ) = FileBackend::splitStoragePath( $params['dir'] ); @@ -748,8 +768,6 @@ class FSFileBackend extends FileBackendStore { /** * Listen for E_WARNING errors and track whether any happen - * - * @return void */ protected function trapWarnings() { $this->hadWarningErrors[] = false; // push to stack @@ -767,7 +785,7 @@ class FSFileBackend extends FileBackendStore { } /** - * @param integer $errno + * @param int $errno * @param string $errstr * @return bool * @access private @@ -792,7 +810,7 @@ class FSFileOpHandle extends FileBackendStoreOpHandle { * @param array $params * @param string $call * @param string $cmd - * @param integer|null $chmodPath + * @param int|null $chmodPath */ public function __construct( FSFileBackend $backend, array $params, $call, $cmd, $chmodPath = null @@ -815,9 +833,14 @@ class FSFileOpHandle extends FileBackendStoreOpHandle { abstract class FSFileBackendList implements Iterator { /** @var Iterator */ protected $iter; - protected $suffixStart; // integer - protected $pos = 0; // integer - /** @var Array */ + + /** @var int */ + protected $suffixStart; + + /** @var int */ + protected $pos = 0; + + /** @var array */ protected $params = array(); /** @@ -864,7 +887,7 @@ abstract class FSFileBackendList implements Iterator { /** * @see Iterator::key() - * @return integer + * @return int */ public function key() { return $this->pos; @@ -880,7 +903,7 @@ abstract class FSFileBackendList implements Iterator { /** * @see Iterator::next() - * @return void + * @throws FileBackendError */ public function next() { try { @@ -894,7 +917,7 @@ abstract class FSFileBackendList implements Iterator { /** * @see Iterator::rewind() - * @return void + * @throws FileBackendError */ public function rewind() { $this->pos = 0; @@ -924,7 +947,7 @@ abstract class FSFileBackendList implements Iterator { * Return only the relative path and normalize slashes to FileBackend-style. * Uses the "real path" since the suffix is based upon that. * - * @param string $path + * @param string $dir * @return string */ protected function getRelPath( $dir ) { diff --git a/includes/filebackend/FileBackend.php b/includes/filebackend/FileBackend.php index 0f449766c0..d042dc4ba3 100644 --- a/includes/filebackend/FileBackend.php +++ b/includes/filebackend/FileBackend.php @@ -60,14 +60,24 @@ * @since 1.19 */ abstract class FileBackend { - protected $name; // string; unique backend name - protected $wikiId; // string; unique wiki name - protected $readOnly; // string; read-only explanation message - protected $parallelize; // string; when to do operations in parallel - protected $concurrency; // integer; how many operations can be done in parallel + /** @var string Unique backend name */ + protected $name; + + /** @var string Unique wiki name */ + protected $wikiId; + + /** @var string Read-only explanation message */ + protected $readOnly; + + /** @var string When to do operations in parallel */ + protected $parallelize; + + /** @var int How many operations can be done in parallel */ + protected $concurrency; /** @var LockManager */ protected $lockManager; + /** @var FileJournal */ protected $fileJournal; @@ -75,7 +85,7 @@ abstract class FileBackend { * Create a new backend instance from configuration. * This should only be called from within FileBackendGroup. * - * $config includes: + * @param array $config Parameters include: * - name : The unique name of this backend. * This should consist of alphanumberic, '-', and '_' characters. * This name should not be changed after use (e.g. with journaling). @@ -93,8 +103,6 @@ abstract class FileBackend { * - parallelize : When to do file operations in parallel (when possible). * Allowed values are "implicit", "explicit" and "off". * - concurrency : How many file operations can be done in parallel. - * - * @param array $config * @throws MWException */ public function __construct( array $config ) { @@ -671,8 +679,7 @@ abstract class FileBackend { * otherwise safe from modification from other processes. Normally, * the file will be a new temp file, which should be adequate. * - * @param array $params Operation parameters - * $params include: + * @param array $params Operation parameters, include: * - srcs : ordered source storage paths (e.g. chunk1, chunk2, ...) * - dst : file system path to 0-byte temp file * - parallelize : try to do operations in parallel when possible @@ -691,8 +698,7 @@ abstract class FileBackend { * However, setting them is not guaranteed to actually do anything. * Additional server configuration may be needed to achieve the desired effect. * - * @param array $params - * $params include: + * @param array $params Parameters include: * - dir : storage directory * - noAccess : try to deny file access (since 1.20) * - noListing : try to deny file listing (since 1.20) @@ -721,8 +727,7 @@ abstract class FileBackend { * This is not guaranteed to actually make files or listings publically hidden. * Additional server configuration may be needed to achieve the desired effect. * - * @param array $params - * $params include: + * @param array $params Parameters include: * - dir : storage directory * - noAccess : try to deny file access * - noListing : try to deny file listing @@ -752,8 +757,7 @@ abstract class FileBackend { * This is not guaranteed to actually make files or listings publically viewable. * Additional server configuration may be needed to achieve the desired effect. * - * @param array $params - * $params include: + * @param array $params Parameters include: * - dir : storage directory * - access : try to allow file access * - listing : try to allow file listing @@ -779,8 +783,7 @@ abstract class FileBackend { * Backends using key/value stores may do nothing unless the directory * is that of an empty container, in which case it will be deleted. * - * @param array $params - * $params include: + * @param array $params Parameters include: * - dir : storage directory * - recursive : recursively delete empty subdirectories first (since 1.20) * - bypassReadOnly : allow writes in read-only mode (since 1.20) @@ -821,8 +824,7 @@ abstract class FileBackend { * Check if a file exists at a storage path in the backend. * This returns false if only a directory exists at the path. * - * @param array $params - * $params include: + * @param array $params Parameters include: * - src : source storage path * - latest : use the latest available data * @return bool|null Returns null on failure @@ -832,8 +834,7 @@ abstract class FileBackend { /** * Get the last-modified timestamp of the file at a storage path. * - * @param array $params - * $params include: + * @param array $params Parameters include: * - src : source storage path * - latest : use the latest available data * @return string|bool TS_MW timestamp or false on failure @@ -844,8 +845,7 @@ abstract class FileBackend { * Get the contents of a file at a storage path in the backend. * This should be avoided for potentially large files. * - * @param array $params - * $params include: + * @param array $params Parameters include: * - src : source storage path * - latest : use the latest available data * @return string|bool Returns false on failure @@ -864,12 +864,11 @@ abstract class FileBackend { * * @see FileBackend::getFileContents() * - * @param array $params - * $params include: + * @param array $params Parameters include: * - srcs : list of source storage paths * - latest : use the latest available data * - parallelize : try to do operations in parallel when possible - * @return Array Map of (path name => string or false on failure) + * @return array Map of (path name => string or false on failure) * @since 1.20 */ abstract public function getFileContentsMulti( array $params ); @@ -877,11 +876,10 @@ abstract class FileBackend { /** * Get the size (bytes) of a file at a storage path in the backend. * - * @param array $params - * $params include: + * @param array $params Parameters include: * - src : source storage path * - latest : use the latest available data - * @return integer|bool Returns false on failure + * @return int|bool Returns false on failure */ abstract public function getFileSize( array $params ); @@ -893,19 +891,17 @@ abstract class FileBackend { * - size : the file size (bytes) * Additional values may be included for internal use only. * - * @param array $params - * $params include: + * @param array $params Parameters include: * - src : source storage path * - latest : use the latest available data - * @return Array|bool|null Returns null on failure + * @return array|bool|null Returns null on failure */ abstract public function getFileStat( array $params ); /** * Get a SHA-1 hash of the file at a storage path in the backend. * - * @param array $params - * $params include: + * @param array $params Parameters include: * - src : source storage path * - latest : use the latest available data * @return string|bool Hash string or false on failure @@ -916,11 +912,10 @@ abstract class FileBackend { * Get the properties of the file at a storage path in the backend. * This gives the result of FSFile::getProps() on a local copy of the file. * - * @param array $params - * $params include: + * @param array $params Parameters include: * - src : source storage path * - latest : use the latest available data - * @return Array Returns FSFile::placeholderProps() on failure + * @return array Returns FSFile::placeholderProps() on failure */ abstract public function getFileProps( array $params ); @@ -931,8 +926,7 @@ abstract class FileBackend { * will be sent if streaming began, while none will be sent otherwise. * Implementations should flush the output buffer before sending data. * - * @param array $params - * $params include: + * @param array $params Parameters include: * - src : source storage path * - headers : list of additional HTTP headers to send on success * - latest : use the latest available data @@ -953,8 +947,7 @@ abstract class FileBackend { * In that later case, there are copies of the file that must stay in sync. * Additionally, further calls to this function may return the same file. * - * @param array $params - * $params include: + * @param array $params Parameters include: * - src : source storage path * - latest : use the latest available data * @return FSFile|null Returns null on failure @@ -973,12 +966,11 @@ abstract class FileBackend { * * @see FileBackend::getLocalReference() * - * @param array $params - * $params include: + * @param array $params Parameters include: * - srcs : list of source storage paths * - latest : use the latest available data * - parallelize : try to do operations in parallel when possible - * @return Array Map of (path name => FSFile or null on failure) + * @return array Map of (path name => FSFile or null on failure) * @since 1.20 */ abstract public function getLocalReferenceMulti( array $params ); @@ -988,8 +980,7 @@ abstract class FileBackend { * The temporary copy will have the same file extension as the source. * Temporary files may be purged when the file object falls out of scope. * - * @param array $params - * $params include: + * @param array $params Parameters include: * - src : source storage path * - latest : use the latest available data * @return TempFSFile|null Returns null on failure @@ -1008,12 +999,11 @@ abstract class FileBackend { * * @see FileBackend::getLocalCopy() * - * @param array $params - * $params include: + * @param array $params Parameters include: * - srcs : list of source storage paths * - latest : use the latest available data * - parallelize : try to do operations in parallel when possible - * @return Array Map of (path name => TempFSFile or null on failure) + * @return array Map of (path name => TempFSFile or null on failure) * @since 1.20 */ abstract public function getLocalCopyMulti( array $params ); @@ -1028,8 +1018,7 @@ abstract class FileBackend { * Otherwise, one would need to use getLocalReference(), which involves loading * the entire file on to local disk. * - * @param array $params - * $params include: + * @param array $params Parameters include: * - src : source storage path * - ttl : lifetime (seconds) if pre-authenticated; default is 1 day * @return string|null @@ -1044,8 +1033,7 @@ abstract class FileBackend { * * Storage backends with eventual consistency might return stale data. * - * @param array $params - * $params include: + * @param array $params Parameters include: * - dir : storage directory * @return bool|null Returns null on failure * @since 1.20 @@ -1064,8 +1052,7 @@ abstract class FileBackend { * * Failures during iteration can result in FileBackendError exceptions (since 1.22). * - * @param array $params - * $params include: + * @param array $params Parameters include: * - dir : storage directory * - topOnly : only return direct child dirs of the directory * @return Traversable|Array|null Returns null on failure @@ -1081,8 +1068,7 @@ abstract class FileBackend { * * Failures during iteration can result in FileBackendError exceptions (since 1.22). * - * @param array $params - * $params include: + * @param array $params Parameters include: * - dir : storage directory * @return Traversable|Array|null Returns null on failure * @since 1.20 @@ -1103,8 +1089,7 @@ abstract class FileBackend { * * Failures during iteration can result in FileBackendError exceptions (since 1.22). * - * @param array $params - * $params include: + * @param array $params Parameters include: * - dir : storage directory * - topOnly : only return direct child files of the directory (since 1.20) * - adviseStat : set to true if stat requests will be made on the files (since 1.22) @@ -1120,8 +1105,7 @@ abstract class FileBackend { * * Failures during iteration can result in FileBackendError exceptions (since 1.22). * - * @param array $params - * $params include: + * @param array $params Parameters include: * - dir : storage directory * - adviseStat : set to true if stat requests will be made on the files (since 1.22) * @return Traversable|Array|null Returns null on failure @@ -1136,7 +1120,6 @@ abstract class FileBackend { * This should be used when stat calls will be made on a known list of a many files. * * @param array $paths Storage paths - * @return void */ public function preloadCache( array $paths ) { } @@ -1146,7 +1129,6 @@ abstract class FileBackend { * If $paths is given, then only the cache for those files will be cleared. * * @param array $paths Storage paths (optional) - * @return void */ public function clearCache( array $paths = null ) { } @@ -1158,7 +1140,7 @@ abstract class FileBackend { * Callers should consider using getScopedFileLocks() instead. * * @param array $paths Storage paths - * @param integer $type LockManager::LOCK_* constant + * @param int $type LockManager::LOCK_* constant * @return Status */ final public function lockFiles( array $paths, $type ) { @@ -1171,7 +1153,7 @@ abstract class FileBackend { * Unlock the files at the given storage paths in the backend. * * @param array $paths Storage paths - * @param integer $type LockManager::LOCK_* constant + * @param int $type LockManager::LOCK_* constant * @return Status */ final public function unlockFiles( array $paths, $type ) { @@ -1191,7 +1173,7 @@ abstract class FileBackend { * @see ScopedLock::factory() * * @param array $paths List of storage paths or map of lock types to path lists - * @param integer|string $type LockManager::LOCK_* constant or "mixed" + * @param int|string $type LockManager::LOCK_* constant or "mixed" * @param Status $status Status to update on lock/unlock * @return ScopedLock|null Returns null on failure */ @@ -1220,7 +1202,7 @@ abstract class FileBackend { * * @param array $ops List of file operations to FileBackend::doOperations() * @param Status $status Status to update on lock/unlock - * @return Array List of ScopedFileLocks or null values + * @return array List of ScopedFileLocks or null values * @since 1.20 */ abstract public function getScopedLocksForOps( array $ops, Status $status ); @@ -1273,7 +1255,7 @@ abstract class FileBackend { * This does not do any path normalization or traversal checks. * * @param string $storagePath - * @return Array (backend, container, rel object) or (null, null, null) + * @return array (backend, container, rel object) or (null, null, null) */ final public static function splitStoragePath( $storagePath ) { if ( self::isStoragePath( $storagePath ) ) { diff --git a/includes/filebackend/FileBackendGroup.php b/includes/filebackend/FileBackendGroup.php index e378d3ce58..491424bf61 100644 --- a/includes/filebackend/FileBackendGroup.php +++ b/includes/filebackend/FileBackendGroup.php @@ -29,12 +29,10 @@ * @since 1.19 */ class FileBackendGroup { - /** - * @var FileBackendGroup - */ + /** @var FileBackendGroup */ protected static $instance = null; - /** @var Array (name => ('class' => string, 'config' => array, 'instance' => object)) */ + /** @var array (name => ('class' => string, 'config' => array, 'instance' => object)) */ protected $backends = array(); protected function __construct() { @@ -54,8 +52,6 @@ class FileBackendGroup { /** * Destroy the singleton instance - * - * @return void */ public static function destroySingleton() { self::$instance = null; @@ -63,8 +59,6 @@ class FileBackendGroup { /** * Register file backends from the global variables - * - * @return void */ protected function initFromGlobals() { global $wgLocalFileRepo, $wgForeignFileRepos, $wgFileBackends; @@ -118,8 +112,7 @@ class FileBackendGroup { /** * Register an array of file backend configurations * - * @param Array $configs - * @return void + * @param array $configs * @throws MWException */ protected function register( array $configs ) { @@ -169,7 +162,7 @@ class FileBackendGroup { * Get the config array for a backend object with a given name * * @param string $name - * @return Array + * @return array * @throws MWException */ public function config( $name ) { diff --git a/includes/filebackend/FileBackendMultiWrite.php b/includes/filebackend/FileBackendMultiWrite.php index 6af5398dab..542d1da52b 100644 --- a/includes/filebackend/FileBackendMultiWrite.php +++ b/includes/filebackend/FileBackendMultiWrite.php @@ -40,15 +40,25 @@ * @since 1.19 */ class FileBackendMultiWrite extends FileBackend { - /** @var Array Prioritized list of FileBackendStore objects */ - protected $backends = array(); // array of (backend index => backends) - protected $masterIndex = -1; // integer; index of master backend - protected $syncChecks = 0; // integer; bitfield - protected $autoResync = false; // boolean + /** @var array Prioritized list of FileBackendStore objects. + * array of (backend index => backends) + */ + protected $backends = array(); + + /** @var int Index of master backend */ + protected $masterIndex = -1; + + /** @var int Bitfield */ + protected $syncChecks = 0; - /** @var Array */ + /** @var bool */ + protected $autoResync = false; + + /** @var array */ protected $noPushDirConts = array(); - protected $noPushQuickOps = false; // boolean + + /** @var bool */ + protected $noPushQuickOps = false; /* Possible internal backend consistency checks */ const CHECK_SIZE = 1; @@ -81,7 +91,7 @@ class FileBackendMultiWrite extends FileBackend { * - noPushQuickOps : (hack) Only apply doQuickOperations() to the master backend. * - noPushDirConts : (hack) Only apply directory functions to the master backend. * - * @param Array $config + * @param array $config * @throws MWException */ public function __construct( array $config ) { @@ -349,7 +359,7 @@ class FileBackendMultiWrite extends FileBackend { * Get a list of file storage paths to read or write for a list of operations * * @param array $ops Same format as doOperations() - * @return Array List of storage paths to files (does not include directories) + * @return array List of storage paths to files (does not include directories) */ protected function fileStoragePathsForOps( array $ops ) { $paths = array(); @@ -380,7 +390,7 @@ class FileBackendMultiWrite extends FileBackend { * * @param array $ops List of file operation arrays * @param FileBackendStore $backend - * @return Array + * @return array */ protected function substOpBatchPaths( array $ops, FileBackendStore $backend ) { $newOps = array(); // operations @@ -402,7 +412,7 @@ class FileBackendMultiWrite extends FileBackend { * * @param array $ops File operation array * @param FileBackendStore $backend - * @return Array + * @return array */ protected function substOpPaths( array $ops, FileBackendStore $backend ) { $newOps = $this->substOpBatchPaths( array( $ops ), $backend ); @@ -415,7 +425,7 @@ class FileBackendMultiWrite extends FileBackend { * * @param array|string $paths List of paths or single string path * @param FileBackendStore $backend - * @return Array|string + * @return array|string */ protected function substPaths( $paths, FileBackendStore $backend ) { return preg_replace( @@ -429,7 +439,7 @@ class FileBackendMultiWrite extends FileBackend { * Substitute the backend of internal storage paths with the proxy backend's name * * @param array|string $paths List of paths or single string path - * @return Array|string + * @return array|string */ protected function unsubstPaths( $paths ) { return preg_replace( diff --git a/includes/filebackend/FileBackendStore.php b/includes/filebackend/FileBackendStore.php index d1e96bca4a..beca79eebf 100644 --- a/includes/filebackend/FileBackendStore.php +++ b/includes/filebackend/FileBackendStore.php @@ -43,7 +43,7 @@ abstract class FileBackendStore extends FileBackend { /** @var ProcessCacheLRU Map of paths to large (RAM/disk) cache items */ protected $expensiveCache; - /** @var Array Map of container names to sharding config */ + /** @var array Map of container names to sharding config */ protected $shardViaHashLevels = array(); /** @var callback Method to get the MIME type of files */ @@ -82,7 +82,7 @@ abstract class FileBackendStore extends FileBackend { * medium restrictions and basic performance constraints. * Do not call this function from places outside FileBackend and FileOp. * - * @return integer Bytes + * @return int Bytes */ final public function maxFileSizeInternal() { return $this->maxFileSize; @@ -135,6 +135,7 @@ abstract class FileBackendStore extends FileBackend { /** * @see FileBackendStore::createInternal() + * @param array $params * @return Status */ abstract protected function doCreateInternal( array $params ); @@ -175,6 +176,7 @@ abstract class FileBackendStore extends FileBackend { /** * @see FileBackendStore::storeInternal() + * @param array $params * @return Status */ abstract protected function doStoreInternal( array $params ); @@ -211,6 +213,7 @@ abstract class FileBackendStore extends FileBackend { /** * @see FileBackendStore::copyInternal() + * @param array $params * @return Status */ abstract protected function doCopyInternal( array $params ); @@ -239,6 +242,7 @@ abstract class FileBackendStore extends FileBackend { /** * @see FileBackendStore::deleteInternal() + * @param array $params * @return Status */ abstract protected function doDeleteInternal( array $params ); @@ -276,6 +280,7 @@ abstract class FileBackendStore extends FileBackend { /** * @see FileBackendStore::moveInternal() + * @param array $params * @return Status */ protected function doMoveInternal( array $params ) { @@ -322,6 +327,7 @@ abstract class FileBackendStore extends FileBackend { /** * @see FileBackendStore::describeInternal() + * @param array $params * @return Status */ protected function doDescribeInternal( array $params ) { @@ -361,6 +367,7 @@ abstract class FileBackendStore extends FileBackend { /** * @see FileBackendStore::concatenate() + * @param array $params * @return Status */ protected function doConcatenate( array $params ) { @@ -457,6 +464,9 @@ abstract class FileBackendStore extends FileBackend { /** * @see FileBackendStore::doPrepare() + * @param $container + * @param string $dir + * @param array $params * @return Status */ protected function doPrepareInternal( $container, $dir, array $params ) { @@ -489,6 +499,9 @@ abstract class FileBackendStore extends FileBackend { /** * @see FileBackendStore::doSecure() + * @param $container + * @param string $dir + * @param array $params * @return Status */ protected function doSecureInternal( $container, $dir, array $params ) { @@ -521,6 +534,9 @@ abstract class FileBackendStore extends FileBackend { /** * @see FileBackendStore::doPublish() + * @param $container + * @param string $dir + * @param array $params * @return Status */ protected function doPublishInternal( $container, $dir, array $params ) { @@ -574,6 +590,9 @@ abstract class FileBackendStore extends FileBackend { /** * @see FileBackendStore::doClean() + * @param $container + * @param string $dir + * @param array $params * @return Status */ protected function doCleanInternal( $container, $dir, array $params ) { @@ -664,7 +683,8 @@ abstract class FileBackendStore extends FileBackend { /** * @see FileBackendStore::getFileContentsMulti() - * @return Array + * @param array $params + * @return array */ protected function doGetFileContentsMulti( array $params ) { $contents = array(); @@ -702,6 +722,7 @@ abstract class FileBackendStore extends FileBackend { /** * @see FileBackendStore::getFileSha1Base36() + * @param array $params * @return bool|string */ protected function doGetFileSha1Base36( array $params ) { @@ -757,7 +778,8 @@ abstract class FileBackendStore extends FileBackend { /** * @see FileBackendStore::getLocalReferenceMulti() - * @return Array + * @param array $params + * @return array */ protected function doGetLocalReferenceMulti( array $params ) { return $this->doGetLocalCopyMulti( $params ); @@ -774,12 +796,14 @@ abstract class FileBackendStore extends FileBackend { /** * @see FileBackendStore::getLocalCopyMulti() - * @return Array + * @param array $params + * @return array */ abstract protected function doGetLocalCopyMulti( array $params ); /** * @see FileBackend::getFileHttpUrl() + * @param array $params * @return string|null */ public function getFileHttpUrl( array $params ) { @@ -821,6 +845,7 @@ abstract class FileBackendStore extends FileBackend { /** * @see FileBackendStore::streamFile() + * @param array $params * @return Status */ protected function doStreamFile( array $params ) { @@ -939,7 +964,7 @@ abstract class FileBackendStore extends FileBackend { * An exception is thrown if an unsupported operation is requested. * * @param array $ops Same format as doOperations() - * @return Array List of FileOp objects + * @return array List of FileOp objects * @throws MWException */ final public function getOperationsInternal( array $ops ) { @@ -979,7 +1004,7 @@ abstract class FileBackendStore extends FileBackend { * normalized. * * @param array $performOps List of FileOp objects - * @return Array (LockManager::LOCK_UW => path list, LockManager::LOCK_EX => path list) + * @return array (LockManager::LOCK_UW => path list, LockManager::LOCK_EX => path list) */ final public function getPathsToLockForOpsInternal( array $performOps ) { // Build up a list of files to lock... @@ -1107,9 +1132,10 @@ abstract class FileBackendStore extends FileBackend { * The resulting Status object fields will correspond * to the order in which the handles where given. * - * @param array $handles List of FileBackendStoreOpHandle objects - * @return Array Map of Status objects + * @param array $fileOpHandles * @throws MWException + * @internal param array $handles List of FileBackendStoreOpHandle objects + * @return array Map of Status objects */ final public function executeOpHandlesInternal( array $fileOpHandles ) { $section = new ProfileSection( __METHOD__ . "-{$this->name}" ); @@ -1132,7 +1158,7 @@ abstract class FileBackendStore extends FileBackend { * @see FileBackendStore::executeOpHandlesInternal() * @param array $fileOpHandles * @throws MWException - * @return Array List of corresponding Status objects + * @return array List of corresponding Status objects */ protected function doExecuteOpHandlesInternal( array $fileOpHandles ) { foreach ( $fileOpHandles as $fileOpHandle ) { // OK if empty @@ -1149,7 +1175,7 @@ abstract class FileBackendStore extends FileBackend { * specific errors, especially in the middle of batch file operations. * * @param array $op Same format as doOperation() - * @return Array + * @return array */ protected function stripInvalidHeadersFromOp( array $op ) { static $longs = array( 'Content-Disposition' ); @@ -1202,7 +1228,6 @@ abstract class FileBackendStore extends FileBackend { * @see FileBackend::clearCache() * * @param array $paths Storage paths (optional) - * @return void */ protected function doClearCache( array $paths = null ) { } @@ -1243,7 +1268,7 @@ abstract class FileBackendStore extends FileBackend { * be scanned by looking in all the container shards. * * @param string $storagePath - * @return Array (container, path, container suffix) or (null, null, null) if invalid + * @return array (container, path, container suffix) or (null, null, null) if invalid */ final protected function resolveStoragePath( $storagePath ) { list( $backend, $container, $relPath ) = self::splitStoragePath( $storagePath ); @@ -1284,7 +1309,7 @@ abstract class FileBackendStore extends FileBackend { * @see FileBackendStore::resolveStoragePath() * * @param string $storagePath - * @return Array (container, path) or (null, null) if invalid + * @return array (container, path) or (null, null) if invalid */ final protected function resolveStoragePathReal( $storagePath ) { list( $container, $relPath, $cShard ) = $this->resolveStoragePath( $storagePath ); @@ -1353,7 +1378,7 @@ abstract class FileBackendStore extends FileBackend { * the container are required to be hashed accordingly. * * @param string $container - * @return Array (integer levels, integer base, repeat flag) or (0, 0, false) + * @return array (integer levels, integer base, repeat flag) or (0, 0, false) */ final protected function getContainerHashLevels( $container ) { if ( isset( $this->shardViaHashLevels[$container] ) ) { @@ -1374,7 +1399,7 @@ abstract class FileBackendStore extends FileBackend { * Get a list of full container shard suffixes for a container * * @param string $container - * @return Array + * @return array */ final protected function getContainerSuffixes( $container ) { $shards = array(); @@ -1444,7 +1469,6 @@ abstract class FileBackendStore extends FileBackend { * * @param string $container Resolved container name * @param array $val Information to cache - * @return void */ final protected function setContainerCache( $container, array $val ) { $this->memCache->add( $this->containerCacheKey( $container ), $val, 14 * 86400 ); @@ -1455,7 +1479,6 @@ abstract class FileBackendStore extends FileBackend { * The cache key is salted for a while to prevent race conditions. * * @param string $container Resolved container name - * @return void */ final protected function deleteContainerCache( $container ) { if ( !$this->memCache->set( $this->containerCacheKey( $container ), 'PURGED', 300 ) ) { @@ -1468,8 +1491,7 @@ abstract class FileBackendStore extends FileBackend { * used in a list of container names, storage paths, or FileOp objects. * This loads the persistent cache values into the process cache. * - * @param Array $items - * @return void + * @param array $items */ final protected function primeContainerCache( array $items ) { $section = new ProfileSection( __METHOD__ . "-{$this->name}" ); @@ -1512,7 +1534,6 @@ abstract class FileBackendStore extends FileBackend { * Only containers that actually exist should appear in the map. * * @param array $containerInfo Map of resolved container names to cached info - * @return void */ protected function doPrimeContainerCache( array $containerInfo ) { } @@ -1534,7 +1555,6 @@ abstract class FileBackendStore extends FileBackend { * * @param string $path Storage path * @param array $val Stat information to cache - * @return void */ final protected function setFileCache( $path, array $val ) { $path = FileBackend::normalizeStoragePath( $path ); @@ -1553,7 +1573,6 @@ abstract class FileBackendStore extends FileBackend { * a file is created at a path were there was none before. * * @param string $path Storage path - * @return void */ final protected function deleteFileCache( $path ) { $path = FileBackend::normalizeStoragePath( $path ); @@ -1571,7 +1590,6 @@ abstract class FileBackendStore extends FileBackend { * This loads the persistent cache values into the process cache. * * @param array $items List of storage paths or FileOps - * @return void */ final protected function primeFileCache( array $items ) { $section = new ProfileSection( __METHOD__ . "-{$this->name}" ); @@ -1614,7 +1632,7 @@ abstract class FileBackendStore extends FileBackend { * Set the 'concurrency' option from a list of operation options * * @param array $opts Map of operation options - * @return Array + * @return array */ final protected function setConcurrencyFlags( array $opts ) { $opts['concurrency'] = 1; // off @@ -1653,19 +1671,17 @@ abstract class FileBackendStore extends FileBackend { * passed to FileBackendStore::executeOpHandlesInternal(). */ abstract class FileBackendStoreOpHandle { - /** @var Array */ + /** @var array */ public $params = array(); // params to caller functions /** @var FileBackendStore */ public $backend; - /** @var Array */ + /** @var array */ public $resourcesToClose = array(); public $call; // string; name that identifies the function called /** * Close all open file handles - * - * @return void */ public function closeResources() { array_map( 'fclose', $this->resourcesToClose ); @@ -1681,13 +1697,17 @@ abstract class FileBackendStoreOpHandle { abstract class FileBackendStoreShardListIterator extends FilterIterator { /** @var FileBackendStore */ protected $backend; - /** @var Array */ + + /** @var array */ protected $params; - protected $container; // string; full container name - protected $directory; // string; resolved relative path + /** @var string Full container name */ + protected $container; + + /** @var string Resolved relative path */ + protected $directory; - /** @var Array */ + /** @var array */ protected $multiShardPaths = array(); // (rel path => 1) /** diff --git a/includes/filebackend/FileOp.php b/includes/filebackend/FileOp.php index c910399d91..538d9b471b 100644 --- a/includes/filebackend/FileOp.php +++ b/includes/filebackend/FileOp.php @@ -34,20 +34,35 @@ * @since 1.19 */ abstract class FileOp { - /** @var Array */ + /** @var array */ protected $params = array(); + /** @var FileBackendStore */ protected $backend; - protected $state = self::STATE_NEW; // integer - protected $failed = false; // boolean - protected $async = false; // boolean - protected $batchId; // string + /** @var int */ + protected $state = self::STATE_NEW; + + /** @var bool */ + protected $failed = false; + + /** @var bool */ + protected $async = false; + + /** @var string */ + protected $batchId; - protected $doOperation = true; // boolean; operation is not a no-op - protected $sourceSha1; // string - protected $overwriteSameCase; // boolean - protected $destExists; // boolean + /** @var bool Operation is not a no-op */ + protected $doOperation = true; + + /** @var string */ + protected $sourceSha1; + + /** @var bool */ + protected $overwriteSameCase; + + /** @var bool */ + protected $destExists; /* Object life-cycle */ const STATE_NEW = 1; @@ -58,7 +73,7 @@ abstract class FileOp { * Build a new batch file operation transaction * * @param FileBackendStore $backend - * @param Array $params + * @param array $params * @throws MWException */ final public function __construct( FileBackendStore $backend, array $params ) { @@ -104,7 +119,6 @@ abstract class FileOp { * Set the batch UUID this operation belongs to * * @param string $batchId - * @return void */ final public function setBatchId( $batchId ) { $this->batchId = $batchId; @@ -132,7 +146,7 @@ abstract class FileOp { /** * Get a new empty predicates array for precheck() * - * @return Array + * @return array */ final public static function newPredicates() { return array( 'exists' => array(), 'sha1' => array() ); @@ -141,7 +155,7 @@ abstract class FileOp { /** * Get a new empty dependency tracking array for paths read/written to * - * @return Array + * @return array */ final public static function newDependencies() { return array( 'read' => array(), 'write' => array() ); @@ -151,7 +165,7 @@ abstract class FileOp { * Update a dependency tracking array to account for this operation * * @param array $deps Prior path reads/writes; format of FileOp::newPredicates() - * @return Array + * @return array */ final public function applyDependencies( array $deps ) { $deps['read'] += array_fill_keys( $this->storagePathsRead(), 1 ); @@ -163,7 +177,7 @@ abstract class FileOp { /** * Check if this operation changes files listed in $paths * - * @param array $paths Prior path reads/writes; format of FileOp::newPredicates() + * @param array $deps Prior path reads/writes; format of FileOp::newPredicates() * @return boolean */ final public function dependsOn( array $deps ) { @@ -186,7 +200,7 @@ abstract class FileOp { * * @param array $oPredicates Pre-op info about files (format of FileOp::newPredicates) * @param array $nPredicates Post-op info about files (format of FileOp::newPredicates) - * @return Array + * @return array */ final public function getJournalEntries( array $oPredicates, array $nPredicates ) { if ( !$this->doOperation ) { @@ -227,7 +241,7 @@ abstract class FileOp { * This must update $predicates for each path that the op can change * except when a failing status object is returned. * - * @param Array $predicates + * @param array $predicates * @return Status */ final public function precheck( array &$predicates ) { @@ -244,6 +258,7 @@ abstract class FileOp { } /** + * @param array $predicates * @return Status */ protected function doPrecheck( array &$predicates ) { @@ -298,7 +313,7 @@ abstract class FileOp { /** * Get the file operation parameters * - * @return Array (required params list, optional params list, list of params that are paths) + * @return array (required params list, optional params list, list of params that are paths) */ protected function allowedParams() { return array( array(), array(), array() ); @@ -307,8 +322,8 @@ abstract class FileOp { /** * Adjust params to FileBackendStore internal file calls * - * @param Array $params - * @return Array (required params list, optional params list) + * @param array $params + * @return array (required params list, optional params list) */ protected function setFlags( array $params ) { return array( 'async' => $this->async ) + $params; @@ -317,7 +332,7 @@ abstract class FileOp { /** * Get a list of storage paths read from for this operation * - * @return Array + * @return array */ public function storagePathsRead() { return array(); @@ -326,7 +341,7 @@ abstract class FileOp { /** * Get a list of storage paths written to for this operation * - * @return Array + * @return array */ public function storagePathsChanged() { return array(); @@ -337,7 +352,7 @@ abstract class FileOp { * Also set the destExists, overwriteSameCase and sourceSha1 member variables. * A bad status will be returned if there is no chance it can be overwritten. * - * @param Array $predicates + * @param array $predicates * @return Status */ protected function precheckDestExistence( array $predicates ) { @@ -389,7 +404,7 @@ abstract class FileOp { * Check if a file will exist in storage when this operation is attempted * * @param string $source Storage path - * @param Array $predicates + * @param array $predicates * @return bool */ final protected function fileExists( $source, array $predicates ) { @@ -406,7 +421,7 @@ abstract class FileOp { * Get the SHA-1 of a file in storage when this operation is attempted * * @param string $source Storage path - * @param Array $predicates + * @param array $predicates * @return string|bool False on failure */ final protected function fileSha1( $source, array $predicates ) { @@ -434,7 +449,6 @@ abstract class FileOp { * Log a file operation failure and preserve any temp files * * @param string $action - * @return void */ final public function logFailure( $action ) { $params = $this->params; diff --git a/includes/filebackend/FileOpBatch.php b/includes/filebackend/FileOpBatch.php index d90b393ff0..32b65baba1 100644 --- a/includes/filebackend/FileOpBatch.php +++ b/includes/filebackend/FileOpBatch.php @@ -149,7 +149,7 @@ class FileOpBatch { * within any given sub-batch do not depend on each other. * This will abort remaining ops on failure. * - * @param Array $pPerformOps + * @param array $pPerformOps * @param Status $status * @return bool Success */ diff --git a/includes/filebackend/SwiftFileBackend.php b/includes/filebackend/SwiftFileBackend.php index d46c66f0b4..5c9fdc2c14 100644 --- a/includes/filebackend/SwiftFileBackend.php +++ b/includes/filebackend/SwiftFileBackend.php @@ -37,26 +37,45 @@ * @since 1.19 */ class SwiftFileBackend extends FileBackendStore { - /** @var CF_Authentication */ - protected $auth; // Swift authentication handler - protected $authTTL; // integer seconds - protected $swiftTempUrlKey; // string; shared secret value for making temp urls - protected $swiftAnonUser; // string; username to handle unauthenticated requests - protected $swiftUseCDN; // boolean; whether CloudFiles CDN is enabled - protected $swiftCDNExpiry; // integer; how long to cache things in the CDN - protected $swiftCDNPurgable; // boolean; whether object CDN purging is enabled + /** @var CF_Authentication Swift authentication handler */ + protected $auth; + + /** @var int TTL in seconds */ + protected $authTTL; + + /** @var string Shared secret value for making temp URLs */ + protected $swiftTempUrlKey; + + /** @var string Username to handle unauthenticated requests */ + protected $swiftAnonUser; + + /** @var bool Whether CloudFiles CDN is enabled */ + protected $swiftUseCDN; + + /** @var int How long to cache things in the CDN */ + protected $swiftCDNExpiry; + + /** @var bool Whether object CDN purging is enabled */ + protected $swiftCDNPurgable; // Rados Gateway specific options - protected $rgwS3AccessKey; // string; S3 access key - protected $rgwS3SecretKey; // string; S3 authentication key + /** @var string S3 access key */ + protected $rgwS3AccessKey; - /** @var CF_Connection */ - protected $conn; // Swift connection handle - protected $sessionStarted = 0; // integer UNIX timestamp + /** @var string S3 authentication key */ + protected $rgwS3SecretKey; + + /** @var CF_Connection Swift connection handle*/ + protected $conn; + + /** @var int UNIX timestamp */ + protected $sessionStarted = 0; /** @var CloudFilesException */ protected $connException; - protected $connErrorTime = 0; // UNIX timestamp + + /** @var int UNIX timestamp */ + protected $connErrorTime = 0; /** @var BagOStuff */ protected $srvCache; @@ -162,7 +181,10 @@ class SwiftFileBackend extends FileBackendStore { /** * @see FileBackendStore::resolveContainerPath() - * @return null + * @param string $container + * @param string $relStoragePath + * @return string|null Returns null when the URL encoded storage path is + * longer than 1024 characters or not UTF-8 encoded. */ protected function resolveContainerPath( $container, $relStoragePath ) { if ( !mb_check_encoding( $relStoragePath, 'UTF-8' ) ) { // mb_string required by CF @@ -664,6 +686,9 @@ class SwiftFileBackend extends FileBackendStore { /** * @see FileBackendStore::doSecureInternal() + * @param string $fullCont + * @param string $dir + * @param array $params * @return Status */ protected function doSecureInternal( $fullCont, $dir, array $params ) { @@ -699,6 +724,9 @@ class SwiftFileBackend extends FileBackendStore { /** * @see FileBackendStore::doPublishInternal() + * @param string $fullCont + * @param string $dir + * @param array $params * @return Status */ protected function doPublishInternal( $fullCont, $dir, array $params ) { @@ -923,6 +951,9 @@ class SwiftFileBackend extends FileBackendStore { /** * @see FileBackendStore::doDirectoryExists() + * @param string $fullCont + * @param string $dir + * @param array $params * @return bool|null */ protected function doDirectoryExists( $fullCont, $dir, array $params ) { @@ -943,6 +974,9 @@ class SwiftFileBackend extends FileBackendStore { /** * @see FileBackendStore::getDirectoryListInternal() + * @param string $fullCont + * @param string $dir + * @param array $params * @return SwiftFileBackendDirList */ public function getDirectoryListInternal( $fullCont, $dir, array $params ) { @@ -951,6 +985,9 @@ class SwiftFileBackend extends FileBackendStore { /** * @see FileBackendStore::getFileListInternal() + * @param string $fullCont + * @param string $dir + * @param array $params * @return SwiftFileBackendFileList */ public function getFileListInternal( $fullCont, $dir, array $params ) { @@ -963,9 +1000,9 @@ class SwiftFileBackend extends FileBackendStore { * @param string $fullCont Resolved container name * @param string $dir Resolved storage directory with no trailing slash * @param string|null $after Resolved container relative path to list items after - * @param integer $limit Max number of items to list + * @param int $limit Max number of items to list * @param array $params Parameters for getDirectoryList() - * @return Array List of container relative resolved paths of directories directly under $dir + * @return array List of container relative resolved paths of directories directly under $dir * @throws FileBackendError */ public function getDirListPageInternal( $fullCont, $dir, &$after, $limit, array $params ) { @@ -1038,9 +1075,9 @@ class SwiftFileBackend extends FileBackendStore { * @param string $fullCont Resolved container name * @param string $dir Resolved storage directory with no trailing slash * @param string|null $after Resolved container relative path of file to list items after - * @param integer $limit Max number of items to list + * @param int $limit Max number of items to list * @param array $params Parameters for getDirectoryList() - * @return Array List of resolved container relative paths of files under $dir + * @return array List of resolved container relative paths of files under $dir * @throws FileBackendError */ public function getFileListPageInternal( $fullCont, $dir, &$after, $limit, array $params ) { @@ -1125,7 +1162,6 @@ class SwiftFileBackend extends FileBackendStore { * * @param string $path Storage path * @param array $val Stat value - * @return void */ public function loadListingStatInternal( $path, array $val ) { $this->cheapCache->set( $path, 'stat', $val ); @@ -1305,7 +1341,7 @@ class SwiftFileBackend extends FileBackendStore { * $params is currently only checked for a 'latest' flag. * * @param array $params - * @return Array + * @return array */ protected function headersFromParams( array $params ) { $hdrs = array(); @@ -1345,7 +1381,13 @@ class SwiftFileBackend extends FileBackendStore { /** * Set read/write permissions for a Swift container. * - * $readGrps is a list of the possible criteria for a request to have + * @see http://swift.openstack.org/misc.html#acls + * + * In general, we don't allow listings to end-users. It's not useful, isn't well-defined + * (lists are truncated to 10000 item with no way to page), and is just a performance risk. + * + * @param CF_Container $contObj Swift container + * @param array $readGrps List of the possible criteria for a request to have * access to read a container. Each item is one of the following formats: * - account:user : Grants access if the request is by the given user * - ".r:" : Grants access if the request is from a referrer host that @@ -1353,19 +1395,9 @@ class SwiftFileBackend extends FileBackendStore { * Setting this to '*' effectively makes a container public. * -".rlistings:" : Grants access if the request is from a referrer host that * matches the expression and the request is for a listing. - * - * $writeGrps is a list of the possible criteria for a request to have + * @param array $writeGrps A list of the possible criteria for a request to have * access to write to a container. Each item is of the following format: * - account:user : Grants access if the request is by the given user - * - * @see http://swift.openstack.org/misc.html#acls - * - * In general, we don't allow listings to end-users. It's not useful, isn't well-defined - * (lists are truncated to 10000 item with no way to page), and is just a performance risk. - * - * @param CF_Container $contObj Swift container - * @param array $readGrps List of read access routes - * @param array $writeGrps List of write access routes * @return Status */ protected function setContainerAccess( @@ -1389,7 +1421,6 @@ class SwiftFileBackend extends FileBackendStore { * This is for Rackspace/Akamai CDNs. * * @param array $objects List of CF_Object items - * @return void */ public function purgeCDNCache( array $objects ) { if ( $this->swiftUseCDN && $this->swiftCDNPurgable ) { @@ -1457,8 +1488,6 @@ class SwiftFileBackend extends FileBackendStore { /** * Close the connection to the Swift proxy - * - * @return void */ protected function closeConnection() { if ( $this->conn ) { @@ -1527,7 +1556,6 @@ class SwiftFileBackend extends FileBackendStore { * Delete a Swift container * * @param string $container Container name - * @return void * @throws CloudFilesException */ protected function deleteContainer( $container ) { @@ -1557,7 +1585,6 @@ class SwiftFileBackend extends FileBackendStore { * @param Status $status null * @param string $func * @param array $params - * @return void */ protected function handleException( Exception $e, $status, $func, array $params ) { if ( $status instanceof Status ) { @@ -1587,7 +1614,8 @@ class SwiftFileBackend extends FileBackendStore { class SwiftFileOpHandle extends FileBackendStoreOpHandle { /** @var CF_Async_Op */ public $cfOp; - /** @var Array */ + + /** @var array */ public $affectedObjects = array(); /** @@ -1614,18 +1642,29 @@ class SwiftFileOpHandle extends FileBackendStoreOpHandle { * @ingroup FileBackend */ abstract class SwiftFileBackendList implements Iterator { - /** @var Array List of path or (path,stat array) entries */ + /** @var array List of path or (path,stat array) entries */ protected $bufferIter = array(); - protected $bufferAfter = null; // string; list items *after* this path - protected $pos = 0; // integer - /** @var Array */ + + /** @var string List items *after* this path */ + protected $bufferAfter = null; + + /** @var int */ + protected $pos = 0; + + /** @var array */ protected $params = array(); /** @var SwiftFileBackend */ protected $backend; - protected $container; // string; container name - protected $dir; // string; storage directory - protected $suffixStart; // integer + + /** @var string Container name */ + protected $container; + + /** @var string Storage directory */ + protected $dir; + + /** @var int */ + protected $suffixStart; const PAGE_SIZE = 9000; // file listing buffer size @@ -1652,7 +1691,7 @@ abstract class SwiftFileBackendList implements Iterator { /** * @see Iterator::key() - * @return integer + * @return int */ public function key() { return $this->pos; @@ -1660,7 +1699,6 @@ abstract class SwiftFileBackendList implements Iterator { /** * @see Iterator::next() - * @return void */ public function next() { // Advance to the next file in the page @@ -1677,7 +1715,6 @@ abstract class SwiftFileBackendList implements Iterator { /** * @see Iterator::rewind() - * @return void */ public function rewind() { $this->pos = 0; @@ -1705,9 +1742,9 @@ abstract class SwiftFileBackendList implements Iterator { * @param string $container Resolved container name * @param string $dir Resolved path relative to container * @param string $after null - * @param integer $limit + * @param int $limit * @param array $params - * @return Traversable|Array + * @return Traversable|array */ abstract protected function pageFromList( $container, $dir, &$after, $limit, array $params ); } @@ -1726,7 +1763,12 @@ class SwiftFileBackendDirList extends SwiftFileBackendList { /** * @see SwiftFileBackendList::pageFromList() - * @return Array + * @param string $container + * @param string $dir + * @param string $after + * @param int $limit + * @param array $params + * @return array */ protected function pageFromList( $container, $dir, &$after, $limit, array $params ) { return $this->backend->getDirListPageInternal( $container, $dir, $after, $limit, $params ); @@ -1754,7 +1796,12 @@ class SwiftFileBackendFileList extends SwiftFileBackendList { /** * @see SwiftFileBackendList::pageFromList() - * @return Array + * @param string $container + * @param string $dir + * @param string $after + * @param int $limit + * @param array $params + * @return array */ protected function pageFromList( $container, $dir, &$after, $limit, array $params ) { return $this->backend->getFileListPageInternal( $container, $dir, $after, $limit, $params ); diff --git a/includes/filebackend/TempFSFile.php b/includes/filebackend/TempFSFile.php index 4d2639f996..c0070ca850 100644 --- a/includes/filebackend/TempFSFile.php +++ b/includes/filebackend/TempFSFile.php @@ -28,9 +28,10 @@ * @ingroup FileBackend */ class TempFSFile extends FSFile { - protected $canDelete = false; // bool; garbage collect the temp file + /** @var bool Garbage collect the temp file */ + protected $canDelete = false; - /** @var Array of active temp files to purge on shutdown */ + /** @var array Active temp files to purge on shutdown */ protected static $instances = array(); /** diff --git a/includes/filebackend/filejournal/DBFileJournal.php b/includes/filebackend/filejournal/DBFileJournal.php index 42f4f1a973..4f64f0222f 100644 --- a/includes/filebackend/filejournal/DBFileJournal.php +++ b/includes/filebackend/filejournal/DBFileJournal.php @@ -34,10 +34,9 @@ class DBFileJournal extends FileJournal { /** * Construct a new instance from configuration. - * $config includes: - * 'wiki' : wiki name to use for LoadBalancer * - * @param $config Array + * @param array $config Includes: + * 'wiki' : wiki name to use for LoadBalancer */ protected function __construct( array $config ) { parent::__construct( $config ); @@ -47,6 +46,8 @@ class DBFileJournal extends FileJournal { /** * @see FileJournal::logChangeBatch() + * @param array $entries + * @param string $batchId * @return Status */ protected function doLogChangeBatch( array $entries, $batchId ) { @@ -90,7 +91,7 @@ class DBFileJournal extends FileJournal { /** * @see FileJournal::doGetCurrentPosition() - * @return integer|false + * @return bool|mixed The value from the field, or false on failure. */ protected function doGetCurrentPosition() { $dbw = $this->getMasterDB(); @@ -103,8 +104,8 @@ class DBFileJournal extends FileJournal { /** * @see FileJournal::doGetPositionAtTime() - * @param $time integer|string timestamp - * @return integer|false + * @param int|string $time Timestamp + * @return bool|mixed The value from the field, or false on failure. */ protected function doGetPositionAtTime( $time ) { $dbw = $this->getMasterDB(); @@ -120,8 +121,9 @@ class DBFileJournal extends FileJournal { /** * @see FileJournal::doGetChangeEntries() - * @return Array - * @throws DBError + * @param int $start + * @param int $limit + * @return array */ protected function doGetChangeEntries( $start, $limit ) { $dbw = $this->getMasterDB(); diff --git a/includes/filebackend/filejournal/FileJournal.php b/includes/filebackend/filejournal/FileJournal.php index fe36ff23ed..3ab9f5d172 100644 --- a/includes/filebackend/filejournal/FileJournal.php +++ b/includes/filebackend/filejournal/FileJournal.php @@ -36,15 +36,17 @@ * @since 1.20 */ abstract class FileJournal { - protected $backend; // string - protected $ttlDays; // integer + /** @var string */ + protected $backend; + + /** @var int */ + protected $ttlDays; /** * Construct a new instance from configuration. - * $config includes: - * 'ttlDays' : days to keep log entries around (false means "forever") * - * @param $config Array + * @param array $config Includes: + * 'ttlDays' : days to keep log entries around (false means "forever") */ protected function __construct( array $config ) { $this->ttlDays = isset( $config['ttlDays'] ) ? $config['ttlDays'] : false; @@ -53,7 +55,7 @@ abstract class FileJournal { /** * Create an appropriate FileJournal object from config * - * @param $config Array + * @param array $config * @param string $backend A registered file backend name * @throws MWException * @return FileJournal @@ -86,13 +88,12 @@ abstract class FileJournal { /** * Log changes made by a batch file operation. - * $entries is an array of log entries, each of which contains: + * + * @param array $entries List of file operations (each an array of parameters) which contain: * op : Basic operation name (create, update, delete) * path : The storage path of the file * newSha1 : The final base 36 SHA-1 of the file - * Note that 'false' should be used as the SHA-1 for non-existing files. - * - * @param array $entries List of file operations (each an array of parameters) + * Note that 'false' should be used as the SHA-1 for non-existing files. * @param string $batchId UUID string that identifies the operation batch * @return Status */ @@ -116,7 +117,7 @@ abstract class FileJournal { /** * Get the position ID of the latest journal entry * - * @return integer|false + * @return int|bool */ final public function getCurrentPosition() { return $this->doGetCurrentPosition(); @@ -124,15 +125,15 @@ abstract class FileJournal { /** * @see FileJournal::getCurrentPosition() - * @return integer|false + * @return int|bool */ abstract protected function doGetCurrentPosition(); /** * Get the position ID of the latest journal entry at some point in time * - * @param $time integer|string timestamp - * @return integer|false + * @param int|string $time timestamp + * @return int|bool */ final public function getPositionAtTime( $time ) { return $this->doGetPositionAtTime( $time ); @@ -140,8 +141,8 @@ abstract class FileJournal { /** * @see FileJournal::getPositionAtTime() - * @param $time integer|string timestamp - * @return integer|false + * @param int|string $time Timestamp + * @return int|bool */ abstract protected function doGetPositionAtTime( $time ); @@ -149,7 +150,10 @@ abstract class FileJournal { * Get an array of file change log entries. * A starting change ID and/or limit can be specified. * - * The result as a list of associative arrays, each having: + * @param $start integer Starting change ID or null + * @param $limit integer Maximum number of items to return + * @param &$next string Updated to the ID of the next entry. + * @return array List of associative arrays, each having: * id : unique, monotonic, ID for this change * batch_uuid : UUID for an operation batch * backend : the backend name @@ -157,12 +161,7 @@ abstract class FileJournal { * path : affected storage path * new_sha1 : base 36 sha1 of the new file had the operation succeeded * timestamp : TS_MW timestamp of the batch change - * Also, $next is updated to the ID of the next entry. - * - * @param $start integer Starting change ID or null - * @param $limit integer Maximum number of items to return - * @param &$next string - * @return Array + * Also, $next is updated to the ID of the next entry. */ final public function getChangeEntries( $start = null, $limit = 0, &$next = null ) { $entries = $this->doGetChangeEntries( $start, $limit ? $limit + 1 : 0 ); @@ -178,7 +177,9 @@ abstract class FileJournal { /** * @see FileJournal::getChangeEntries() - * @return Array + * @param int $start + * @param int $limit + * @return array */ abstract protected function doGetChangeEntries( $start, $limit ); @@ -205,8 +206,8 @@ abstract class FileJournal { class NullFileJournal extends FileJournal { /** * @see FileJournal::doLogChangeBatch() - * @param $entries array - * @param $batchId string + * @param array $entries + * @param string $batchId * @return Status */ protected function doLogChangeBatch( array $entries, $batchId ) { @@ -215,7 +216,7 @@ class NullFileJournal extends FileJournal { /** * @see FileJournal::doGetCurrentPosition() - * @return integer|false + * @return int|bool */ protected function doGetCurrentPosition() { return false; @@ -223,8 +224,8 @@ class NullFileJournal extends FileJournal { /** * @see FileJournal::doGetPositionAtTime() - * @param $time integer|string timestamp - * @return integer|false + * @param int|string $time timestamp + * @return int|bool */ protected function doGetPositionAtTime( $time ) { return false; @@ -232,7 +233,9 @@ class NullFileJournal extends FileJournal { /** * @see FileJournal::doGetChangeEntries() - * @return Array + * @param int $start + * @param int $limit + * @return array */ protected function doGetChangeEntries( $start, $limit ) { return array(); diff --git a/includes/filebackend/lockmanager/DBLockManager.php b/includes/filebackend/lockmanager/DBLockManager.php index 68d684e851..4418a83069 100644 --- a/includes/filebackend/lockmanager/DBLockManager.php +++ b/includes/filebackend/lockmanager/DBLockManager.php @@ -37,7 +37,7 @@ * @since 1.19 */ abstract class DBLockManager extends QuorumLockManager { - /** @var Array Map of DB names to server config */ + /** @var array Map of DB names to server config */ protected $dbServers; // (DB name => server config array) /** @var BagOStuff */ protected $statusCache; @@ -46,13 +46,13 @@ abstract class DBLockManager extends QuorumLockManager { protected $safeDelay; // integer number of seconds protected $session = 0; // random integer - /** @var Array Map Database connections (DB name => Database) */ + /** @var array Map Database connections (DB name => Database) */ protected $conns = array(); /** * Construct a new instance from configuration. * - * $config paramaters include: + * @param array $config Paramaters include: * - dbServers : Associative array of DB names to server configuration. * Configuration is an associative array that includes: * - host : DB server name @@ -70,8 +70,6 @@ abstract class DBLockManager extends QuorumLockManager { * - lockExpiry : Lock timeout (seconds) for dropped connections. [optional] * This tells the DB server how long to wait before assuming * connection failure and releasing all the locks for a session. - * - * @param array $config */ public function __construct( array $config ) { parent::__construct( $config ); @@ -126,6 +124,7 @@ abstract class DBLockManager extends QuorumLockManager { /** * @see QuorumLockManager::isServerUp() + * @param string $lockSrv * @return bool */ protected function isServerUp( $lockSrv ) { @@ -146,7 +145,7 @@ abstract class DBLockManager extends QuorumLockManager { /** * Get (or reuse) a connection to a lock DB * - * @param $lockDb string + * @param string $lockDb * @return DatabaseBase * @throws DBError */ @@ -185,9 +184,8 @@ abstract class DBLockManager extends QuorumLockManager { /** * Do additional initialization for new lock DB connection * - * @param $lockDb string - * @param $db DatabaseBase - * @return void + * @param string $lockDb + * @param DatabaseBase $db * @throws DBError */ protected function initConnection( $lockDb, DatabaseBase $db ) { @@ -209,7 +207,7 @@ abstract class DBLockManager extends QuorumLockManager { /** * Log a lock request failure to the cache * - * @param $lockDb string + * @param string $lockDb * @return bool Success */ protected function cacheRecordFailure( $lockDb ) { @@ -221,7 +219,7 @@ abstract class DBLockManager extends QuorumLockManager { /** * Get a cache key for recent query misses for a DB * - * @param $lockDb string + * @param string $lockDb * @return string */ protected function getMissKey( $lockDb ) { @@ -247,7 +245,7 @@ abstract class DBLockManager extends QuorumLockManager { * @ingroup LockManager */ class MySqlLockManager extends DBLockManager { - /** @var Array Mapping of lock types to the type actually used */ + /** @var array Mapping of lock types to the type actually used */ protected $lockTypeMap = array( self::LOCK_SH => self::LOCK_SH, self::LOCK_UW => self::LOCK_SH, @@ -255,8 +253,8 @@ class MySqlLockManager extends DBLockManager { ); /** - * @param $lockDb string - * @param $db DatabaseBase + * @param string $lockDb + * @param DatabaseBase $db */ protected function initConnection( $lockDb, DatabaseBase $db ) { # Let this transaction see lock rows from other transactions @@ -268,6 +266,9 @@ class MySqlLockManager extends DBLockManager { * This does not use GET_LOCK() per http://bugs.mysql.com/bug.php?id=1118. * * @see DBLockManager::getLocksOnServer() + * @param string $lockSrv + * @param array $paths + * @param string $type * @return Status */ protected function doGetLocksOnServer( $lockSrv, array $paths, $type ) { @@ -364,7 +365,7 @@ class MySqlLockManager extends DBLockManager { * @ingroup LockManager */ class PostgreSqlLockManager extends DBLockManager { - /** @var Array Mapping of lock types to the type actually used */ + /** @var array Mapping of lock types to the type actually used */ protected $lockTypeMap = array( self::LOCK_SH => self::LOCK_SH, self::LOCK_UW => self::LOCK_SH, diff --git a/includes/filebackend/lockmanager/FSLockManager.php b/includes/filebackend/lockmanager/FSLockManager.php index ec9bca5065..e97ec114aa 100644 --- a/includes/filebackend/lockmanager/FSLockManager.php +++ b/includes/filebackend/lockmanager/FSLockManager.php @@ -34,7 +34,7 @@ * @since 1.19 */ class FSLockManager extends LockManager { - /** @var Array Mapping of lock types to the type actually used */ + /** @var array Mapping of lock types to the type actually used */ protected $lockTypeMap = array( self::LOCK_SH => self::LOCK_SH, self::LOCK_UW => self::LOCK_SH, @@ -43,16 +43,14 @@ class FSLockManager extends LockManager { protected $lockDir; // global dir for all servers - /** @var Array Map of (locked key => lock file handle) */ + /** @var array Map of (locked key => lock file handle) */ protected $handles = array(); /** * Construct a new instance from configuration. * - * $config includes: + * @param array $config Includes: * - lockDirectory : Directory containing the lock files - * - * @param array $config */ function __construct( array $config ) { parent::__construct( $config ); @@ -62,8 +60,8 @@ class FSLockManager extends LockManager { /** * @see LockManager::doLock() - * @param $paths array - * @param $type int + * @param array $paths + * @param int $type * @return Status */ protected function doLock( array $paths, $type ) { @@ -87,8 +85,8 @@ class FSLockManager extends LockManager { /** * @see LockManager::doUnlock() - * @param $paths array - * @param $type int + * @param array $paths + * @param int $type * @return Status */ protected function doUnlock( array $paths, $type ) { @@ -104,8 +102,8 @@ class FSLockManager extends LockManager { /** * Lock a single resource key * - * @param $path string - * @param $type integer + * @param array $path + * @param int $type * @return Status */ protected function doSingleLock( $path, $type ) { @@ -149,8 +147,8 @@ class FSLockManager extends LockManager { /** * Unlock a single resource key * - * @param $path string - * @param $type integer + * @param array $path + * @param int $type * @return Status */ protected function doSingleUnlock( $path, $type ) { @@ -192,8 +190,8 @@ class FSLockManager extends LockManager { } /** - * @param $path string - * @param $handlesToClose array + * @param string $path + * @param array $handlesToClose * @return Status */ private function closeLockHandles( $path, array $handlesToClose ) { @@ -211,7 +209,7 @@ class FSLockManager extends LockManager { } /** - * @param $path string + * @param string $path * @return Status */ private function pruneKeyLockFiles( $path ) { @@ -229,7 +227,7 @@ class FSLockManager extends LockManager { /** * Get the path to the lock file for a key - * @param $path string + * @param string $path * @return string */ protected function getLockPath( $path ) { diff --git a/includes/filebackend/lockmanager/LSLockManager.php b/includes/filebackend/lockmanager/LSLockManager.php index 80643c1a1e..539a780be7 100644 --- a/includes/filebackend/lockmanager/LSLockManager.php +++ b/includes/filebackend/lockmanager/LSLockManager.php @@ -37,17 +37,17 @@ * @since 1.19 */ class LSLockManager extends QuorumLockManager { - /** @var Array Mapping of lock types to the type actually used */ + /** @var array Mapping of lock types to the type actually used */ protected $lockTypeMap = array( self::LOCK_SH => self::LOCK_SH, self::LOCK_UW => self::LOCK_SH, self::LOCK_EX => self::LOCK_EX ); - /** @var Array Map of server names to server config */ + /** @var array Map of server names to server config */ protected $lockServers; // (server name => server config array) - /** @var Array Map Server connections (server name => resource) */ + /** @var array Map Server connections (server name => resource) */ protected $conns = array(); protected $connTimeout; // float number of seconds @@ -56,7 +56,7 @@ class LSLockManager extends QuorumLockManager { /** * Construct a new instance from configuration. * - * $config paramaters include: + * @param array $config Paramaters include: * - lockServers : Associative array of server names to configuration. * Configuration is an associative array that includes: * - host : IP address/hostname @@ -65,8 +65,6 @@ class LSLockManager extends QuorumLockManager { * - srvsByBucket : Array of 1-16 consecutive integer keys, starting from 0, * each having an odd-numbered list of server names (peers) as values. * - connTimeout : Lock server connection attempt timeout. [optional] - * - * @param array $config */ public function __construct( array $config ) { parent::__construct( $config ); @@ -87,6 +85,9 @@ class LSLockManager extends QuorumLockManager { /** * @see QuorumLockManager::getLocksOnServer() + * @param string $lockSrv + * @param array $paths + * @param int $type * @return Status */ protected function getLocksOnServer( $lockSrv, array $paths, $type ) { @@ -108,6 +109,9 @@ class LSLockManager extends QuorumLockManager { /** * @see QuorumLockManager::freeLocksOnServer() + * @param string $lockSrv + * @param array $paths + * @param int $type * @return Status */ protected function freeLocksOnServer( $lockSrv, array $paths, $type ) { @@ -146,6 +150,7 @@ class LSLockManager extends QuorumLockManager { /** * @see QuorumLockManager::isServerUp() + * @param string $lockSrv * @return bool */ protected function isServerUp( $lockSrv ) { @@ -155,10 +160,10 @@ class LSLockManager extends QuorumLockManager { /** * Send a command and get back the response * - * @param $lockSrv string - * @param $action string - * @param $type string - * @param $values Array + * @param string $lockSrv + * @param string $action + * @param string $type + * @param array $values * @return string|bool */ protected function sendCommand( $lockSrv, $action, $type, $values ) { @@ -186,7 +191,7 @@ class LSLockManager extends QuorumLockManager { /** * Get (or reuse) a connection to a lock server * - * @param $lockSrv string + * @param string $lockSrv * @return resource */ protected function getConnection( $lockSrv ) { diff --git a/includes/filebackend/lockmanager/LockManager.php b/includes/filebackend/lockmanager/LockManager.php index eca153bc06..7e06e489da 100644 --- a/includes/filebackend/lockmanager/LockManager.php +++ b/includes/filebackend/lockmanager/LockManager.php @@ -43,14 +43,14 @@ * @since 1.19 */ abstract class LockManager { - /** @var Array Mapping of lock types to the type actually used */ + /** @var array Mapping of lock types to the type actually used */ protected $lockTypeMap = array( self::LOCK_SH => self::LOCK_SH, self::LOCK_UW => self::LOCK_EX, // subclasses may use self::LOCK_SH self::LOCK_EX => self::LOCK_EX ); - /** @var Array Map of (resource path => lock type => count) */ + /** @var array Map of (resource path => lock type => count) */ protected $locksHeld = array(); protected $domain; // string; domain (usually wiki ID) @@ -64,12 +64,10 @@ abstract class LockManager { /** * Construct a new instance from configuration * - * $config paramaters include: + * @param array $config Paramaters include: * - domain : Domain (usually wiki ID) that all resources are relative to [optional] * - lockTTL : Age (in seconds) at which resource locks should expire. * This only applies if locks are not tied to a connection/process. - * - * @param $config Array */ public function __construct( array $config ) { $this->domain = isset( $config['domain'] ) ? $config['domain'] : wfWikiID(); @@ -87,8 +85,8 @@ abstract class LockManager { * Lock the resources at the given abstract paths * * @param array $paths List of resource names - * @param $type integer LockManager::LOCK_* constant - * @param integer $timeout Timeout in seconds (0 means non-blocking) (since 1.21) + * @param int $type LockManager::LOCK_* constant + * @param int $timeout Timeout in seconds (0 means non-blocking) (since 1.21) * @return Status */ final public function lock( array $paths, $type = self::LOCK_EX, $timeout = 0 ) { @@ -99,7 +97,7 @@ abstract class LockManager { * Lock the resources at the given abstract paths * * @param array $pathsByType Map of LockManager::LOCK_* constants to lists of paths - * @param integer $timeout Timeout in seconds (0 means non-blocking) (since 1.21) + * @param int $timeout Timeout in seconds (0 means non-blocking) (since 1.21) * @return Status * @since 1.22 */ @@ -127,7 +125,7 @@ abstract class LockManager { * Unlock the resources at the given abstract paths * * @param array $paths List of paths - * @param $type integer LockManager::LOCK_* constant + * @param int $type LockManager::LOCK_* constant * @return Status */ final public function unlock( array $paths, $type = self::LOCK_EX ) { @@ -155,7 +153,7 @@ abstract class LockManager { * Before hashing, the path will be prefixed with the domain ID. * This should be used interally for lock key or file names. * - * @param $path string + * @param string $path * @return string */ final protected function sha1Base36Absolute( $path ) { @@ -167,7 +165,7 @@ abstract class LockManager { * Before hashing, the path will be prefixed with the domain ID. * This should be used interally for lock key or file names. * - * @param $path string + * @param string $path * @return string */ final protected function sha1Base16Absolute( $path ) { @@ -178,8 +176,8 @@ abstract class LockManager { * Normalize the $paths array by converting LOCK_UW locks into the * appropriate type and removing any duplicated paths for each lock type. * - * @param array $paths Map of LockManager::LOCK_* constants to lists of paths - * @return Array + * @param array $pathsByType Map of LockManager::LOCK_* constants to lists of paths + * @return array * @since 1.22 */ final protected function normalizePathsByType( array $pathsByType ) { @@ -193,7 +191,7 @@ abstract class LockManager { /** * @see LockManager::lockByType() - * @param array $paths Map of LockManager::LOCK_* constants to lists of paths + * @param array $pathsByType Map of LockManager::LOCK_* constants to lists of paths * @return Status * @since 1.22 */ @@ -220,14 +218,14 @@ abstract class LockManager { * Lock resources with the given keys and lock type * * @param array $paths List of paths - * @param $type integer LockManager::LOCK_* constant + * @param int $type LockManager::LOCK_* constant * @return Status */ abstract protected function doLock( array $paths, $type ); /** * @see LockManager::unlockByType() - * @param array $paths Map of LockManager::LOCK_* constants to lists of paths + * @param array $pathsByType Map of LockManager::LOCK_* constants to lists of paths * @return Status * @since 1.22 */ @@ -244,7 +242,7 @@ abstract class LockManager { * Unlock resources with the given keys and lock type * * @param array $paths List of paths - * @param $type integer LockManager::LOCK_* constant + * @param int $type LockManager::LOCK_* constant * @return Status */ abstract protected function doUnlock( array $paths, $type ); diff --git a/includes/filebackend/lockmanager/LockManagerGroup.php b/includes/filebackend/lockmanager/LockManagerGroup.php index 451b79ebb9..ecf396af22 100644 --- a/includes/filebackend/lockmanager/LockManagerGroup.php +++ b/includes/filebackend/lockmanager/LockManagerGroup.php @@ -29,12 +29,12 @@ * @since 1.19 */ class LockManagerGroup { - /** @var Array (domain => LockManager) */ + /** @var array (domain => LockManager) */ protected static $instances = array(); protected $domain; // string; domain (usually wiki ID) - /** @var Array of (name => ('class' => ..., 'config' => ..., 'instance' => ...)) */ + /** @var array of (name => ('class' => ..., 'config' => ..., 'instance' => ...)) */ protected $managers = array(); /** @@ -45,7 +45,7 @@ class LockManagerGroup { } /** - * @param string $domain Domain (usually wiki ID) + * @param bool|string $domain Domain (usually wiki ID). Default: false. * @return LockManagerGroup */ public static function singleton( $domain = false ) { @@ -60,8 +60,6 @@ class LockManagerGroup { /** * Destroy the singleton instances - * - * @return void */ public static function destroySingletons() { self::$instances = array(); @@ -69,8 +67,6 @@ class LockManagerGroup { /** * Register lock managers from the global variables - * - * @return void */ protected function initFromGlobals() { global $wgLockManagers; @@ -81,8 +77,7 @@ class LockManagerGroup { /** * Register an array of file lock manager configurations * - * @param $configs Array - * @return void + * @param array $configs * @throws MWException */ protected function register( array $configs ) { @@ -108,7 +103,7 @@ class LockManagerGroup { /** * Get the lock manager object with a given name * - * @param $name string + * @param string $name * @return LockManager * @throws MWException */ @@ -129,8 +124,8 @@ class LockManagerGroup { /** * Get the config array for a lock manager object with a given name * - * @param $name string - * @return Array + * @param string $name + * @return array * @throws MWException */ public function config( $name ) { diff --git a/includes/filebackend/lockmanager/MemcLockManager.php b/includes/filebackend/lockmanager/MemcLockManager.php index 8b8c20316f..254c69328f 100644 --- a/includes/filebackend/lockmanager/MemcLockManager.php +++ b/includes/filebackend/lockmanager/MemcLockManager.php @@ -36,31 +36,31 @@ * @since 1.20 */ class MemcLockManager extends QuorumLockManager { - /** @var Array Mapping of lock types to the type actually used */ + /** @var array Mapping of lock types to the type actually used */ protected $lockTypeMap = array( self::LOCK_SH => self::LOCK_SH, self::LOCK_UW => self::LOCK_SH, self::LOCK_EX => self::LOCK_EX ); - /** @var Array Map server names to MemcachedBagOStuff objects */ + /** @var array Map server names to MemcachedBagOStuff objects */ protected $bagOStuffs = array(); - /** @var Array */ - protected $serversUp = array(); // (server name => bool) - protected $session = ''; // string; random UUID + /** @var array (server name => bool) */ + protected $serversUp = array(); + + /** @var string random UUID */ + protected $session = ''; /** * Construct a new instance from configuration. * - * $config paramaters include: + * @param array $config Paramaters include: * - lockServers : Associative array of server names to ":" strings. * - srvsByBucket : Array of 1-16 consecutive integer keys, starting from 0, * each having an odd-numbered list of server names (peers) as values. * - memcConfig : Configuration array for ObjectCache::newFromParams. [optional] * If set, this must use one of the memcached classes. - * - * @param array $config * @throws MWException */ public function __construct( array $config ) { @@ -88,7 +88,7 @@ class MemcLockManager extends QuorumLockManager { $this->session = wfRandomString( 32 ); } - // @TODO: change this code to work in one batch + // @todo Change this code to work in one batch protected function getLocksOnServer( $lockSrv, array $pathsByType ) { $status = Status::newGood(); @@ -110,7 +110,7 @@ class MemcLockManager extends QuorumLockManager { return $status; } - // @TODO: change this code to work in one batch + // @todo Change this code to work in one batch protected function freeLocksOnServer( $lockSrv, array $pathsByType ) { $status = Status::newGood(); @@ -123,6 +123,9 @@ class MemcLockManager extends QuorumLockManager { /** * @see QuorumLockManager::getLocksOnServer() + * @param string $lockSrv + * @param array $paths + * @param string $type * @return Status */ protected function doGetLocksOnServer( $lockSrv, array $paths, $type ) { @@ -196,6 +199,9 @@ class MemcLockManager extends QuorumLockManager { /** * @see QuorumLockManager::freeLocksOnServer() + * @param string $lockSrv + * @param array $paths + * @param string $type * @return Status */ protected function doFreeLocksOnServer( $lockSrv, array $paths, $type ) { @@ -256,6 +262,7 @@ class MemcLockManager extends QuorumLockManager { /** * @see QuorumLockManager::isServerUp() + * @param string $lockSrv * @return bool */ protected function isServerUp( $lockSrv ) { @@ -287,7 +294,7 @@ class MemcLockManager extends QuorumLockManager { } /** - * @param $path string + * @param string $path * @return string */ protected function recordKeyForPath( $path ) { @@ -295,15 +302,15 @@ class MemcLockManager extends QuorumLockManager { } /** - * @return Array An empty lock structure for a key + * @return array An empty lock structure for a key */ protected static function newLockArray() { return array( self::LOCK_SH => array(), self::LOCK_EX => array() ); } /** - * @param $a array - * @return Array An empty lock structure for a key + * @param array $a + * @return array An empty lock structure for a key */ protected static function sanitizeLockArray( $a ) { if ( is_array( $a ) && isset( $a[self::LOCK_EX] ) && isset( $a[self::LOCK_SH] ) ) { @@ -316,7 +323,7 @@ class MemcLockManager extends QuorumLockManager { } /** - * @param $memc MemcachedBagOStuff + * @param MemcachedBagOStuff $memc * @param array $keys List of keys to acquire * @return bool */ @@ -354,9 +361,8 @@ class MemcLockManager extends QuorumLockManager { } /** - * @param $memc MemcachedBagOStuff + * @param MemcachedBagOStuff $memc * @param array $keys List of acquired keys - * @return void */ protected function releaseMutexes( MemcachedBagOStuff $memc, array $keys ) { foreach ( $keys as $key ) { diff --git a/includes/filebackend/lockmanager/QuorumLockManager.php b/includes/filebackend/lockmanager/QuorumLockManager.php index 749e934766..d17074e8bc 100644 --- a/includes/filebackend/lockmanager/QuorumLockManager.php +++ b/includes/filebackend/lockmanager/QuorumLockManager.php @@ -29,9 +29,10 @@ * @since 1.20 */ abstract class QuorumLockManager extends LockManager { - /** @var Array Map of bucket indexes to peer server lists */ + /** @var array Map of bucket indexes to peer server lists */ protected $srvsByBucket = array(); // (bucket index => (lsrv1, lsrv2, ...)) - /** @var Array Map of degraded buckets */ + + /** @var array Map of degraded buckets */ protected $degradedBuckets = array(); // (buckey index => UNIX timestamp) final protected function doLock( array $paths, $type ) { @@ -121,7 +122,7 @@ abstract class QuorumLockManager extends LockManager { * Attempt to acquire locks with the peers for a bucket. * This is all or nothing; if any key is locked then this totally fails. * - * @param $bucket integer + * @param int $bucket * @param array $pathsByType Map of LockManager::LOCK_* constants to lists of paths * @return Status */ @@ -163,7 +164,7 @@ abstract class QuorumLockManager extends LockManager { /** * Attempt to release locks with the peers for a bucket * - * @param $bucket integer + * @param int $bucket * @param array $pathsByType Map of LockManager::LOCK_* constants to lists of paths * @return Status */ @@ -199,8 +200,8 @@ abstract class QuorumLockManager extends LockManager { * Get the bucket for resource path. * This should avoid throwing any exceptions. * - * @param $path string - * @return integer + * @param string $path + * @return int */ protected function getBucketFromPath( $path ) { $prefix = substr( sha1( $path ), 0, 2 ); // first 2 hex chars (8 bits) @@ -211,7 +212,7 @@ abstract class QuorumLockManager extends LockManager { * Check if a lock server is up. * This should process cache results to reduce RTT. * - * @param $lockSrv string + * @param string $lockSrv * @return bool */ abstract protected function isServerUp( $lockSrv ); @@ -219,7 +220,7 @@ abstract class QuorumLockManager extends LockManager { /** * Get a connection to a lock server and acquire locks * - * @param $lockSrv string + * @param string $lockSrv * @param array $pathsByType Map of LockManager::LOCK_* constants to lists of paths * @return Status */ @@ -230,7 +231,7 @@ abstract class QuorumLockManager extends LockManager { * * Subclasses must effectively implement this or releaseAllLocks(). * - * @param $lockSrv string + * @param string $lockSrv * @param array $pathsByType Map of LockManager::LOCK_* constants to lists of paths * @return Status */ diff --git a/includes/filebackend/lockmanager/RedisLockManager.php b/includes/filebackend/lockmanager/RedisLockManager.php index 3863610b83..5540f61355 100644 --- a/includes/filebackend/lockmanager/RedisLockManager.php +++ b/includes/filebackend/lockmanager/RedisLockManager.php @@ -38,7 +38,7 @@ * @since 1.22 */ class RedisLockManager extends QuorumLockManager { - /** @var Array Mapping of lock types to the type actually used */ + /** @var array Mapping of lock types to the type actually used */ protected $lockTypeMap = array( self::LOCK_SH => self::LOCK_SH, self::LOCK_UW => self::LOCK_SH, @@ -47,21 +47,21 @@ class RedisLockManager extends QuorumLockManager { /** @var RedisConnectionPool */ protected $redisPool; - /** @var Array Map server names to hostname/IP and port numbers */ + + /** @var array Map server names to hostname/IP and port numbers */ protected $lockServers = array(); - protected $session = ''; // string; random UUID + /** @var string random UUID */ + protected $session = ''; /** * Construct a new instance from configuration. * - * $config paramaters include: + * @param array $config Parameters include: * - lockServers : Associative array of server names to ":" strings. * - srvsByBucket : Array of 1-16 consecutive integer keys, starting from 0, * each having an odd-numbered list of server names (peers) as values. * - redisConfig : Configuration for RedisConnectionPool::__construct(). - * - * @param Array $config * @throws MWException */ public function __construct( array $config ) { @@ -100,7 +100,7 @@ class RedisLockManager extends QuorumLockManager { return $status; } - // @TODO: change this code to work in one batch + // @todo Change this code to work in one batch protected function freeLocksOnServer( $lockSrv, array $pathsByType ) { $status = Status::newGood(); @@ -269,7 +269,7 @@ LUA; } /** - * @param $path string + * @param string $path * @return string */ protected function recordKeyForPath( $path ) { diff --git a/includes/filebackend/lockmanager/ScopedLock.php b/includes/filebackend/lockmanager/ScopedLock.php index b35b934abe..2056e101f5 100644 --- a/includes/filebackend/lockmanager/ScopedLock.php +++ b/includes/filebackend/lockmanager/ScopedLock.php @@ -34,9 +34,11 @@ class ScopedLock { /** @var LockManager */ protected $manager; + /** @var Status */ protected $status; - /** @var Array Map of lock types to resource paths */ + + /** @var array Map of lock types to resource paths */ protected $pathsByType; /** @@ -55,14 +57,13 @@ class ScopedLock { * Any locks are released once this object goes out of scope. * The status object is updated with any errors or warnings. * - * $type can be "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 LockManager $manager * @param array $paths List of storage paths or map of lock types to path lists - * @param integer|string $type LockManager::LOCK_* constant or "mixed" + * @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 integer $timeout Timeout in seconds (0 means non-blocking) (since 1.22) + * @param int $timeout Timeout in seconds (0 means non-blocking) (since 1.22) * @return ScopedLock|null Returns null on failure */ public static function factory( @@ -84,7 +85,6 @@ 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 ) { -- 2.20.1