* contents as the new contents to be written there.
*
* $opts is an associative of boolean flags, including:
- * 'force' : Errors that would normally cause a rollback do not.
- * The remaining operations are still attempted if any fail.
+ * 'force' : Operation precondition errors no longer trigger an abort.
+ * Any remaining operations are still attempted. Unexpected
+ * failures may still cause remaning operations to be aborted.
* 'nonLocking' : No locks are acquired for the operations.
* This can increase performance for non-critical writes.
* This has no effect unless the 'force' flag is set.
* otherwise safe from modification from other processes. Normally,
* the file will be a new temp file, which should be adequate.
* $params include:
- * srcs : ordered source storage paths (e.g. chunk1, chunk2, ...)
- * dst : file system path to 0-byte temp file
+ * srcs : ordered source storage paths (e.g. chunk1, chunk2, ...)
+ * dst : file system path to 0-byte temp file
*
* @param $params Array Operation parameters
* @return Status
*
* $params include:
* dir : storage directory
- * topOnly : only return direct child directories of the directory
+ * topOnly : only return direct child dirs of the directory
*
* @return Traversable|Array|null Returns null on failure
* @since 1.20
*
* $params include:
* dir : storage directory
- * topOnly : only return direct child files of the directory
+ * topOnly : only return direct child files of the directory (@since 1.20)
*
* @return Traversable|Array|null Returns null on failure
*/
/**
* @see FileBackend::getDirectoryList()
- * @return Array|null|Traversable
+ * @return Traversable|Array|null Returns null on failure
*/
final public function getDirectoryList( array $params ) {
list( $fullCont, $dir, $shard ) = $this->resolveStoragePath( $params['dir'] );
* @param $container string Resolved container name
* @param $dir string Resolved path relative to container
* @param $params Array
- * @return Traversable|Array|null
+ * @return Traversable|Array|null Returns null on failure
*/
abstract public function getDirectoryListInternal( $container, $dir, array $params );
/**
* @see FileBackend::getFileList()
- * @return Array|null|Traversable
+ * @return Traversable|Array|null Returns null on failure
*/
final public function getFileList( array $params ) {
list( $fullCont, $dir, $shard ) = $this->resolveStoragePath( $params['dir'] );
* @param $container string Resolved container name
* @param $dir string Resolved path relative to container
* @param $params Array
- * @return Traversable|Array|null
+ * @return Traversable|Array|null Returns null on failure
*/
abstract public function getFileListInternal( $container, $dir, array $params );
* Move a cache entry to the top (such as when accessed)
*
* @param $path string Storage path
+ * @return void
*/
protected function pingCache( $path ) {
if ( isset( $this->cache[$path] ) ) {
* Move a cache entry to the top (such as when accessed)
*
* @param $path string Storage path
+ * @return void
*/
protected function pingExpensiveCache( $path ) {
if ( isset( $this->expensiveCache[$path] ) ) {
* @return bool
*/
public function valid() {
- if ( $this->iter == null ) {
+ if ( $this->iter === null ) {
return false; // some failure?
} elseif ( is_array( $this->iter ) ) {
return ( current( $this->iter ) !== false ); // no paths can have this value
* @return bool
*/
public function valid() {
- return ( current( $this->bufferIter ) !== false ); // no paths can have this value
+ if ( $this->bufferIter === null ) {
+ return false; // some failure?
+ } else {
+ return ( current( $this->bufferIter ) !== false ); // no paths can have this value
+ }
}
/**
* @param $after string|null
* @param $limit integer
* @param $params Array
- * @return Traversable|Array|null
+ * @return Traversable|Array|null Returns null on failure
*/
abstract protected function pageFromList( $container, $dir, &$after, $limit, array $params );
}
/**
* @see SwiftFileBackendList::pageFromList()
- * @return Array
+ * @return Array|null
*/
protected function pageFromList( $container, $dir, &$after, $limit, array $params ) {
return $this->backend->getDirListPageInternal( $container, $dir, $after, $limit, $params );
/**
* @see SwiftFileBackendList::pageFromList()
- * @return Array
+ * @return Array|null
*/
protected function pageFromList( $container, $dir, &$after, $limit, array $params ) {
return $this->backend->getFileListPageInternal( $container, $dir, $after, $limit, $params );