MultiWriteBagOStuff.php

Go to the documentation of this file.

<?php
use Wikimedia\ObjectFactory;
 
class MultiWriteBagOStuff extends BagOStuff {
    protected $caches;
    protected $asyncWrites = false;
    protected $cacheIndexes = [];
 
    const UPGRADE_TTL = 3600; // TTL when a key is copied to a higher cache tier
 
    public function __construct( $params ) {
        parent::__construct( $params );
 
        if ( empty( $params['caches'] ) || !is_array( $params['caches'] ) ) {
            throw new InvalidArgumentException(
                __METHOD__ . ': "caches" parameter must be an array of caches'
            );
        }
 
        $this->caches = [];
        foreach ( $params['caches'] as $cacheInfo ) {
            if ( $cacheInfo instanceof BagOStuff ) {
                $this->caches[] = $cacheInfo;
            } else {
                if ( !isset( $cacheInfo['args'] ) ) {
                    // B/C for when $cacheInfo was for ObjectCache::newFromParams().
                    // Callers intenting this to be for ObjectFactory::getObjectFromSpec
                    // should have set "args" per the docs above. Doings so avoids extra
                    // (likely harmless) params (factory/class/calls) ending up in "args".
                    $cacheInfo['args'] = [ $cacheInfo ];
                }
                $this->caches[] = ObjectFactory::getObjectFromSpec( $cacheInfo );
            }
        }
        $this->mergeFlagMaps( $this->caches );
 
        $this->asyncWrites = (
            isset( $params['replication'] ) &&
            $params['replication'] === 'async' &&
            is_callable( $this->asyncHandler )
        );
 
        $this->cacheIndexes = array_keys( $this->caches );
    }
 
    public function setDebug( $debug ) {
        foreach ( $this->caches as $cache ) {
            $cache->setDebug( $debug );
        }
    }
 
    public function get( $key, $flags = 0 ) {
        if ( ( $flags & self::READ_LATEST ) == self::READ_LATEST ) {
            // If the latest write was a delete(), we do NOT want to fallback
            // to the other tiers and possibly see the old value. Also, this
            // is used by merge(), which only needs to hit the primary.
            return $this->caches[0]->get( $key, $flags );
        }
 
        $value = false;
        $missIndexes = []; // backends checked
        foreach ( $this->caches as $i => $cache ) {
            $value = $cache->get( $key, $flags );
            if ( $value !== false ) {
                break;
            }
            $missIndexes[] = $i;
        }
 
        if ( $value !== false
            && $missIndexes
            && ( $flags & self::READ_VERIFIED ) == self::READ_VERIFIED
        ) {
            // Backfill the value to the higher (and often faster/smaller) cache tiers
            $this->doWrite(
                $missIndexes,
                $this->asyncWrites,
                'set',
                [ $key, $value, self::UPGRADE_TTL ]
            );
        }
 
        return $value;
    }
    public function set( $key, $value, $exptime = 0, $flags = 0 ) {
        return $this->doWrite(
            $this->cacheIndexes,
            $this->usesAsyncWritesGivenFlags( $flags ),
            __FUNCTION__,
            func_get_args()
        );
    }
 
    public function delete( $key, $flags = 0 ) {
        return $this->doWrite(
            $this->cacheIndexes,
            $this->usesAsyncWritesGivenFlags( $flags ),
            __FUNCTION__,
            func_get_args()
        );
    }
 
    public function add( $key, $value, $exptime = 0, $flags = 0 ) {
        // Try the write to the top-tier cache
        $ok = $this->doWrite(
            [ 0 ],
            $this->usesAsyncWritesGivenFlags( $flags ),
            __FUNCTION__,
            func_get_args()
        );
 
        if ( $ok ) {
            // Relay the add() using set() if it succeeded. This is meant to handle certain
            // migration scenarios where the same store might get written to twice for certain
            // keys. In that case, it does not make sense to return false due to "self-conflicts".
            return $this->doWrite(
                array_slice( $this->cacheIndexes, 1 ),
                $this->usesAsyncWritesGivenFlags( $flags ),
                'set',
                [ $key, $value, $exptime, $flags ]
            );
        }
 
        return false;
    }
 
    public function merge( $key, callable $callback, $exptime = 0, $attempts = 10, $flags = 0 ) {
        return $this->doWrite(
            $this->cacheIndexes,
            $this->usesAsyncWritesGivenFlags( $flags ),
            __FUNCTION__,
            func_get_args()
        );
    }
 
    public function changeTTL( $key, $exptime = 0, $flags = 0 ) {
        return $this->doWrite(
            $this->cacheIndexes,
            $this->usesAsyncWritesGivenFlags( $flags ),
            __FUNCTION__,
            func_get_args()
        );
    }
 
    public function lock( $key, $timeout = 6, $expiry = 6, $rclass = '' ) {
        // Only need to lock the first cache; also avoids deadlocks
        return $this->caches[0]->lock( $key, $timeout, $expiry, $rclass );
    }
 
    public function unlock( $key ) {
        // Only the first cache is locked
        return $this->caches[0]->unlock( $key );
    }
    public function deleteObjectsExpiringBefore( $date, $progressCallback = false ) {
        $ret = false;
        foreach ( $this->caches as $cache ) {
            if ( $cache->deleteObjectsExpiringBefore( $date, $progressCallback ) ) {
                $ret = true;
            }
        }
 
        return $ret;
    }
 
    public function getMulti( array $keys, $flags = 0 ) {
        // Just iterate over each key in order to handle all the backfill logic
        $res = [];
        foreach ( $keys as $key ) {
            $val = $this->get( $key, $flags );
            if ( $val !== false ) {
                $res[$key] = $val;
            }
        }
 
        return $res;
    }
 
    public function setMulti( array $data, $exptime = 0, $flags = 0 ) {
        return $this->doWrite(
            $this->cacheIndexes,
            $this->usesAsyncWritesGivenFlags( $flags ),
            __FUNCTION__,
            func_get_args()
        );
    }
 
    public function deleteMulti( array $data, $flags = 0 ) {
        return $this->doWrite(
            $this->cacheIndexes,
            $this->usesAsyncWritesGivenFlags( $flags ),
            __FUNCTION__,
            func_get_args()
        );
    }
 
    public function incr( $key, $value = 1 ) {
        return $this->doWrite(
            $this->cacheIndexes,
            $this->asyncWrites,
            __FUNCTION__,
            func_get_args()
        );
    }
 
    public function decr( $key, $value = 1 ) {
        return $this->doWrite(
            $this->cacheIndexes,
            $this->asyncWrites,
            __FUNCTION__,
            func_get_args()
        );
    }
 
    public function incrWithInit( $key, $ttl, $value = 1, $init = 1 ) {
        return $this->doWrite(
            $this->cacheIndexes,
            $this->asyncWrites,
            __FUNCTION__,
            func_get_args()
        );
    }
 
    public function getLastError() {
        return $this->caches[0]->getLastError();
    }
 
    public function clearLastError() {
        $this->caches[0]->clearLastError();
    }
    protected function doWrite( $indexes, $asyncWrites, $method, array $args ) {
        $ret = true;
 
        if ( array_diff( $indexes, [ 0 ] ) && $asyncWrites && $method !== 'merge' ) {
            // Deep-clone $args to prevent misbehavior when something writes an
            // object to the BagOStuff then modifies it afterwards, e.g. T168040.
            $args = unserialize( serialize( $args ) );
        }
 
        foreach ( $indexes as $i ) {
            $cache = $this->caches[$i];
            if ( $i == 0 || !$asyncWrites ) {
                // First store or in sync mode: write now and get result
                if ( !$cache->$method( ...$args ) ) {
                    $ret = false;
                }
            } else {
                // Secondary write in async mode: do not block this HTTP request
                $logger = $this->logger;
                ( $this->asyncHandler )(
                    function () use ( $cache, $method, $args, $logger ) {
                        if ( !$cache->$method( ...$args ) ) {
                            $logger->warning( "Async $method op failed" );
                        }
                    }
                );
            }
        }
 
        return $ret;
    }
 
    protected function usesAsyncWritesGivenFlags( $flags ) {
        return ( ( $flags & self::WRITE_SYNC ) == self::WRITE_SYNC ) ? false : $this->asyncWrites;
    }
 
    public function makeKeyInternal( $keyspace, $args ) {
        return $this->caches[0]->makeKeyInternal( ...func_get_args() );
    }
 
    public function makeKey( $class, $component = null ) {
        return $this->caches[0]->makeKey( ...func_get_args() );
    }
 
    public function makeGlobalKey( $class, $component = null ) {
        return $this->caches[0]->makeGlobalKey( ...func_get_args() );
    }
 
    protected function doGet( $key, $flags = 0, &$casToken = null ) {
        throw new LogicException( __METHOD__ . ': proxy class does not need this method.' );
    }
}