* @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
/**
* Placeholder file properties to use for files that don't exist
*
- * @return Array
+ * @return array
*/
public static function placeholderProps() {
$info = array();
* Exract image size information
*
* @param array $gis
- * @return Array
+ * @return array
*/
protected function extractImageSizeInfo( array $gis ) {
$info = array();
*
* @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 ) {
* @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();
/**
}
}
+ /**
+ * @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'] );
/**
* @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'] );
/**
* @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'] );
/**
* Listen for E_WARNING errors and track whether any happen
- *
- * @return void
*/
protected function trapWarnings() {
$this->hadWarningErrors[] = false; // push to stack
}
/**
- * @param integer $errno
+ * @param int $errno
* @param string $errstr
* @return bool
* @access private
* @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
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();
/**
/**
* @see Iterator::key()
- * @return integer
+ * @return int
*/
public function key() {
return $this->pos;
/**
* @see Iterator::next()
- * @return void
+ * @throws FileBackendError
*/
public function next() {
try {
/**
* @see Iterator::rewind()
- * @return void
+ * @throws FileBackendError
*/
public function rewind() {
$this->pos = 0;
* 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 ) {
* @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;
* 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).
* - 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 ) {
* 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
* 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)
* 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
* 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
* 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)
* 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
/**
* 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
* 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
*
* @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 );
/**
* 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 );
* - 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
* 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 );
* 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
* 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
*
* @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 );
* 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
*
* @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 );
* 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
*
* 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
*
* 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
*
* 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
*
* 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)
*
* 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
* 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 ) {
}
* 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 ) {
}
* 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 ) {
* 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 ) {
* @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
*/
*
* @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 );
* 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 ) ) {
* @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() {
/**
* Destroy the singleton instance
- *
- * @return void
*/
public static function destroySingleton() {
self::$instance = null;
/**
* Register file backends from the global variables
- *
- * @return void
*/
protected function initFromGlobals() {
global $wgLocalFileRepo, $wgForeignFileRepos, $wgFileBackends;
/**
* Register an array of file backend configurations
*
- * @param Array $configs
- * @return void
+ * @param array $configs
* @throws MWException
*/
protected function register( array $configs ) {
* 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 ) {
* @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;
* - 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 ) {
* 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();
*
* @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
*
* @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 );
*
* @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(
* 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(
/** @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 */
* 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;
/**
* @see FileBackendStore::createInternal()
+ * @param array $params
* @return Status
*/
abstract protected function doCreateInternal( array $params );
/**
* @see FileBackendStore::storeInternal()
+ * @param array $params
* @return Status
*/
abstract protected function doStoreInternal( array $params );
/**
* @see FileBackendStore::copyInternal()
+ * @param array $params
* @return Status
*/
abstract protected function doCopyInternal( array $params );
/**
* @see FileBackendStore::deleteInternal()
+ * @param array $params
* @return Status
*/
abstract protected function doDeleteInternal( array $params );
/**
* @see FileBackendStore::moveInternal()
+ * @param array $params
* @return Status
*/
protected function doMoveInternal( array $params ) {
/**
* @see FileBackendStore::describeInternal()
+ * @param array $params
* @return Status
*/
protected function doDescribeInternal( array $params ) {
/**
* @see FileBackendStore::concatenate()
+ * @param array $params
* @return Status
*/
protected function doConcatenate( array $params ) {
/**
* @see FileBackendStore::doPrepare()
+ * @param $container
+ * @param string $dir
+ * @param array $params
* @return Status
*/
protected function doPrepareInternal( $container, $dir, array $params ) {
/**
* @see FileBackendStore::doSecure()
+ * @param $container
+ * @param string $dir
+ * @param array $params
* @return Status
*/
protected function doSecureInternal( $container, $dir, array $params ) {
/**
* @see FileBackendStore::doPublish()
+ * @param $container
+ * @param string $dir
+ * @param array $params
* @return Status
*/
protected function doPublishInternal( $container, $dir, array $params ) {
/**
* @see FileBackendStore::doClean()
+ * @param $container
+ * @param string $dir
+ * @param array $params
* @return Status
*/
protected function doCleanInternal( $container, $dir, array $params ) {
/**
* @see FileBackendStore::getFileContentsMulti()
- * @return Array
+ * @param array $params
+ * @return array
*/
protected function doGetFileContentsMulti( array $params ) {
$contents = array();
/**
* @see FileBackendStore::getFileSha1Base36()
+ * @param array $params
* @return bool|string
*/
protected function doGetFileSha1Base36( array $params ) {
/**
* @see FileBackendStore::getLocalReferenceMulti()
- * @return Array
+ * @param array $params
+ * @return array
*/
protected function doGetLocalReferenceMulti( array $params ) {
return $this->doGetLocalCopyMulti( $params );
/**
* @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 ) {
/**
* @see FileBackendStore::streamFile()
+ * @param array $params
* @return Status
*/
protected function doStreamFile( array $params ) {
* 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 ) {
* 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...
* 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}" );
* @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
* 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' );
* @see FileBackend::clearCache()
*
* @param array $paths Storage paths (optional)
- * @return void
*/
protected function doClearCache( array $paths = null ) {
}
* 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 );
* @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 );
* 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] ) ) {
* 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();
*
* @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 );
* 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 ) ) {
* 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}" );
* 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 ) {
}
*
* @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 );
* 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 );
* 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}" );
* 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
* 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 );
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)
/**
* @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;
* 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 ) {
* Set the batch UUID this operation belongs to
*
* @param string $batchId
- * @return void
*/
final public function setBatchId( $batchId ) {
$this->batchId = $batchId;
/**
* Get a new empty predicates array for precheck()
*
- * @return Array
+ * @return array
*/
final public static function newPredicates() {
return array( 'exists' => array(), 'sha1' => array() );
/**
* 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() );
* 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 );
/**
* 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 ) {
*
* @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 ) {
* 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 ) {
}
/**
+ * @param array $predicates
* @return Status
*/
protected function doPrecheck( array &$predicates ) {
/**
* 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() );
/**
* 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;
/**
* Get a list of storage paths read from for this operation
*
- * @return Array
+ * @return array
*/
public function storagePathsRead() {
return array();
/**
* Get a list of storage paths written to for this operation
*
- * @return Array
+ * @return array
*/
public function storagePathsChanged() {
return array();
* 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 ) {
* 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 ) {
* 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 ) {
* Log a file operation failure and preserve any temp files
*
* @param string $action
- * @return void
*/
final public function logFailure( $action ) {
$params = $this->params;
* 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
*/
* @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;
/**
* @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
/**
* @see FileBackendStore::doSecureInternal()
+ * @param string $fullCont
+ * @param string $dir
+ * @param array $params
* @return Status
*/
protected function doSecureInternal( $fullCont, $dir, array $params ) {
/**
* @see FileBackendStore::doPublishInternal()
+ * @param string $fullCont
+ * @param string $dir
+ * @param array $params
* @return Status
*/
protected function doPublishInternal( $fullCont, $dir, array $params ) {
/**
* @see FileBackendStore::doDirectoryExists()
+ * @param string $fullCont
+ * @param string $dir
+ * @param array $params
* @return bool|null
*/
protected function doDirectoryExists( $fullCont, $dir, array $params ) {
/**
* @see FileBackendStore::getDirectoryListInternal()
+ * @param string $fullCont
+ * @param string $dir
+ * @param array $params
* @return SwiftFileBackendDirList
*/
public function getDirectoryListInternal( $fullCont, $dir, array $params ) {
/**
* @see FileBackendStore::getFileListInternal()
+ * @param string $fullCont
+ * @param string $dir
+ * @param array $params
* @return SwiftFileBackendFileList
*/
public function getFileListInternal( $fullCont, $dir, array $params ) {
* @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 ) {
* @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 ) {
*
* @param string $path Storage path
* @param array $val Stat value
- * @return void
*/
public function loadListingStatInternal( $path, array $val ) {
$this->cheapCache->set( $path, 'stat', $val );
* $params is currently only checked for a 'latest' flag.
*
* @param array $params
- * @return Array
+ * @return array
*/
protected function headersFromParams( array $params ) {
$hdrs = array();
/**
* 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:<regex>" : Grants access if the request is from a referrer host that
* Setting this to '*' effectively makes a container public.
* -".rlistings:<regex>" : 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(
* 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 ) {
/**
* Close the connection to the Swift proxy
- *
- * @return void
*/
protected function closeConnection() {
if ( $this->conn ) {
* Delete a Swift container
*
* @param string $container Container name
- * @return void
* @throws CloudFilesException
*/
protected function deleteContainer( $container ) {
* @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 ) {
class SwiftFileOpHandle extends FileBackendStoreOpHandle {
/** @var CF_Async_Op */
public $cfOp;
- /** @var Array */
+
+ /** @var array */
public $affectedObjects = array();
/**
* @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
/**
* @see Iterator::key()
- * @return integer
+ * @return int
*/
public function key() {
return $this->pos;
/**
* @see Iterator::next()
- * @return void
*/
public function next() {
// Advance to the next file in the page
/**
* @see Iterator::rewind()
- * @return void
*/
public function rewind() {
$this->pos = 0;
* @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 );
}
/**
* @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 );
/**
* @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 );
* @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();
/**
/**
* 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 );
/**
* @see FileJournal::logChangeBatch()
+ * @param array $entries
+ * @param string $batchId
* @return Status
*/
protected function doLogChangeBatch( array $entries, $batchId ) {
/**
* @see FileJournal::doGetCurrentPosition()
- * @return integer|false
+ * @return bool|mixed The value from the field, or false on failure.
*/
protected function doGetCurrentPosition() {
$dbw = $this->getMasterDB();
/**
* @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();
/**
* @see FileJournal::doGetChangeEntries()
- * @return Array
- * @throws DBError
+ * @param int $start
+ * @param int $limit
+ * @return array
*/
protected function doGetChangeEntries( $start, $limit ) {
$dbw = $this->getMasterDB();
* @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;
/**
* 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
/**
* 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
*/
/**
* Get the position ID of the latest journal entry
*
- * @return integer|false
+ * @return int|bool
*/
final public function getCurrentPosition() {
return $this->doGetCurrentPosition();
/**
* @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 );
/**
* @see FileJournal::getPositionAtTime()
- * @param $time integer|string timestamp
- * @return integer|false
+ * @param int|string $time Timestamp
+ * @return int|bool
*/
abstract protected function doGetPositionAtTime( $time );
* 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
* 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 );
/**
* @see FileJournal::getChangeEntries()
- * @return Array
+ * @param int $start
+ * @param int $limit
+ * @return array
*/
abstract protected function doGetChangeEntries( $start, $limit );
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 ) {
/**
* @see FileJournal::doGetCurrentPosition()
- * @return integer|false
+ * @return int|bool
*/
protected function doGetCurrentPosition() {
return false;
/**
* @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;
/**
* @see FileJournal::doGetChangeEntries()
- * @return Array
+ * @param int $start
+ * @param int $limit
+ * @return array
*/
protected function doGetChangeEntries( $start, $limit ) {
return array();
* @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;
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
* - 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 );
/**
* @see QuorumLockManager::isServerUp()
+ * @param string $lockSrv
* @return bool
*/
protected function isServerUp( $lockSrv ) {
/**
* Get (or reuse) a connection to a lock DB
*
- * @param $lockDb string
+ * @param string $lockDb
* @return DatabaseBase
* @throws DBError
*/
/**
* 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 ) {
/**
* Log a lock request failure to the cache
*
- * @param $lockDb string
+ * @param string $lockDb
* @return bool Success
*/
protected function cacheRecordFailure( $lockDb ) {
/**
* Get a cache key for recent query misses for a DB
*
- * @param $lockDb string
+ * @param string $lockDb
* @return string
*/
protected function getMissKey( $lockDb ) {
* @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,
);
/**
- * @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
* 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 ) {
* @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,
* @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,
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 );
/**
* @see LockManager::doLock()
- * @param $paths array
- * @param $type int
+ * @param array $paths
+ * @param int $type
* @return Status
*/
protected function doLock( array $paths, $type ) {
/**
* @see LockManager::doUnlock()
- * @param $paths array
- * @param $type int
+ * @param array $paths
+ * @param int $type
* @return Status
*/
protected function doUnlock( array $paths, $type ) {
/**
* Lock a single resource key
*
- * @param $path string
- * @param $type integer
+ * @param array $path
+ * @param int $type
* @return Status
*/
protected function doSingleLock( $path, $type ) {
/**
* Unlock a single resource key
*
- * @param $path string
- * @param $type integer
+ * @param array $path
+ * @param int $type
* @return Status
*/
protected function doSingleUnlock( $path, $type ) {
}
/**
- * @param $path string
- * @param $handlesToClose array
+ * @param string $path
+ * @param array $handlesToClose
* @return Status
*/
private function closeLockHandles( $path, array $handlesToClose ) {
}
/**
- * @param $path string
+ * @param string $path
* @return Status
*/
private function pruneKeyLockFiles( $path ) {
/**
* Get the path to the lock file for a key
- * @param $path string
+ * @param string $path
* @return string
*/
protected function getLockPath( $path ) {
* @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
/**
* 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
* - 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 );
/**
* @see QuorumLockManager::getLocksOnServer()
+ * @param string $lockSrv
+ * @param array $paths
+ * @param int $type
* @return Status
*/
protected function getLocksOnServer( $lockSrv, array $paths, $type ) {
/**
* @see QuorumLockManager::freeLocksOnServer()
+ * @param string $lockSrv
+ * @param array $paths
+ * @param int $type
* @return Status
*/
protected function freeLocksOnServer( $lockSrv, array $paths, $type ) {
/**
* @see QuorumLockManager::isServerUp()
+ * @param string $lockSrv
* @return bool
*/
protected function isServerUp( $lockSrv ) {
/**
* 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 ) {
/**
* Get (or reuse) a connection to a lock server
*
- * @param $lockSrv string
+ * @param string $lockSrv
* @return resource
*/
protected function getConnection( $lockSrv ) {
* @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)
/**
* 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();
* 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 ) {
* 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
*/
* 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 ) {
* 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 ) {
* 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 ) {
* 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 ) {
/**
* @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
*/
* 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
*/
* 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 );
* @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();
/**
}
/**
- * @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 ) {
/**
* Destroy the singleton instances
- *
- * @return void
*/
public static function destroySingletons() {
self::$instances = array();
/**
* Register lock managers from the global variables
- *
- * @return void
*/
protected function initFromGlobals() {
global $wgLockManagers;
/**
* Register an array of file lock manager configurations
*
- * @param $configs Array
- * @return void
+ * @param array $configs
* @throws MWException
*/
protected function register( array $configs ) {
/**
* Get the lock manager object with a given name
*
- * @param $name string
+ * @param string $name
* @return LockManager
* @throws MWException
*/
/**
* 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 ) {
* @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 "<IP>:<port>" 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 ) {
$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();
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();
/**
* @see QuorumLockManager::getLocksOnServer()
+ * @param string $lockSrv
+ * @param array $paths
+ * @param string $type
* @return Status
*/
protected function doGetLocksOnServer( $lockSrv, array $paths, $type ) {
/**
* @see QuorumLockManager::freeLocksOnServer()
+ * @param string $lockSrv
+ * @param array $paths
+ * @param string $type
* @return Status
*/
protected function doFreeLocksOnServer( $lockSrv, array $paths, $type ) {
/**
* @see QuorumLockManager::isServerUp()
+ * @param string $lockSrv
* @return bool
*/
protected function isServerUp( $lockSrv ) {
}
/**
- * @param $path string
+ * @param string $path
* @return string
*/
protected function recordKeyForPath( $path ) {
}
/**
- * @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] ) ) {
}
/**
- * @param $memc MemcachedBagOStuff
+ * @param MemcachedBagOStuff $memc
* @param array $keys List of keys to acquire
* @return bool
*/
}
/**
- * @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 ) {
* @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 ) {
* 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
*/
/**
* 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
*/
* 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)
* 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 );
/**
* 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
*/
*
* 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
*/
* @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,
/** @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 "<IP>:<port>" 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 ) {
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();
}
/**
- * @param $path string
+ * @param string $path
* @return string
*/
protected function recordKeyForPath( $path ) {
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;
/**
* 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(
* 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 ) {
dépôts / lhc / web / wiklou.git / commitdiff