BagOStuff.php

Go to the documentation of this file.

<?php
use Liuggio\StatsdClient\Factory\StatsdDataFactoryInterface;
use Psr\Log\LoggerAwareInterface;
use Psr\Log\LoggerInterface;
use Psr\Log\NullLogger;
use Wikimedia\LightweightObjectStore\ExpirationAwareness;
use Wikimedia\LightweightObjectStore\StorageAwareness;
use Wikimedia\ScopedCallback;
 
abstract class BagOStuff implements
    ExpirationAwareness,
    StorageAwareness,
    IStoreKeyEncoder,
    LoggerAwareInterface
{
    protected $stats;
    protected $logger;
    protected $asyncHandler;
    protected $wrapperInfoByPrefix = [];
 
    protected $attrMap = [];
 
    protected $keyspace;
 
    protected $debugMode = true;
 
    private $wallClockOverride;
 
    public const READ_LATEST = 1; // if supported, avoid reading stale data due to replication
    public const READ_VERIFIED = 2; // promise that the caller handles detection of staleness
    public const WRITE_SYNC = 4; // if supported, block until the write is fully replicated
    public const WRITE_CACHE_ONLY = 8; // only change state of the in-memory cache
    public const WRITE_ALLOW_SEGMENTS = 16; // allow partitioning of the value if it is large
    public const WRITE_PRUNE_SEGMENTS = 32; // delete all the segments if the value is partitioned
    public const WRITE_BACKGROUND = 64; // if supported, do not block on completion until the next read
 
    protected const GLOBAL_KEYSPACE = 'global';
    protected const GLOBAL_PREFIX = 'global:';
    protected const GLOBAL_PREFIX_LEN = 7;
 
    protected const ARG0_KEY = 0;
    protected const ARG0_KEYARR = 1;
    protected const ARG0_KEYMAP = 2;
    protected const ARG0_NONKEY = 3;
 
    protected const RES_KEYMAP = 0;
    protected const RES_NONKEY = 1;
 
    private const WRAPPER_STATS_GROUP = 0;
    private const WRAPPER_COLLECTION_CALLBACK = 1;
 
    public function __construct( array $params = [] ) {
        $this->keyspace = $params['keyspace'] ?? 'local';
        $this->asyncHandler = $params['asyncHandler'] ?? null;
        $this->stats = $params['stats'] ?? new NullStatsdDataFactory();
        $this->setLogger( $params['logger'] ?? new NullLogger() );
    }
 
    public function setLogger( LoggerInterface $logger ) {
        $this->logger = $logger;
    }
 
    public function getLogger() : LoggerInterface {
        return $this->logger;
    }
 
    public function setDebug( $enabled ) {
        wfDeprecated( __METHOD__, '1.36' );
    }
 
    final public function getWithSetCallback( $key, $exptime, $callback, $flags = 0 ) {
        $value = $this->get( $key, $flags );
 
        if ( $value === false ) {
            $value = $callback( $exptime );
            if ( $value !== false && $exptime >= 0 ) {
                $this->set( $key, $value, $exptime, $flags );
            }
        }
 
        return $value;
    }
 
    abstract public function get( $key, $flags = 0 );
 
    abstract public function set( $key, $value, $exptime = 0, $flags = 0 );
 
    abstract public function delete( $key, $flags = 0 );
 
    abstract public function add( $key, $value, $exptime = 0, $flags = 0 );
 
    abstract public function merge(
        $key,
        callable $callback,
        $exptime = 0,
        $attempts = 10,
        $flags = 0
    );
 
    abstract public function changeTTL( $key, $exptime = 0, $flags = 0 );
 
    abstract public function lock( $key, $timeout = 6, $expiry = 6, $rclass = '' );
 
    abstract public function unlock( $key );
 
    final public function getScopedLock( $key, $timeout = 6, $expiry = 30, $rclass = '' ) {
        $expiry = min( $expiry ?: INF, self::TTL_DAY );
 
        if ( !$this->lock( $key, $timeout, $expiry, $rclass ) ) {
            return null;
        }
 
        $lSince = $this->getCurrentTime(); // lock timestamp
 
        return new ScopedCallback( function () use ( $key, $lSince, $expiry ) {
            $latency = 0.050; // latency skew (err towards keeping lock present)
            $age = ( $this->getCurrentTime() - $lSince + $latency );
            if ( ( $age + $latency ) >= $expiry ) {
                $this->logger->warning(
                    "Lock for {key} held too long ({age} sec).",
                    [ 'key' => $key, 'age' => $age ]
                );
                return; // expired; it's not "safe" to delete the key
            }
            $this->unlock( $key );
        } );
    }
 
    abstract public function deleteObjectsExpiringBefore(
        $timestamp,
        callable $progress = null,
        $limit = INF
    );
 
    abstract public function getMulti( array $keys, $flags = 0 );
 
    abstract public function setMulti( array $valueByKey, $exptime = 0, $flags = 0 );
 
    abstract public function deleteMulti( array $keys, $flags = 0 );
 
    abstract public function changeTTLMulti( array $keys, $exptime, $flags = 0 );
 
    abstract public function incr( $key, $value = 1, $flags = 0 );
 
    abstract public function decr( $key, $value = 1, $flags = 0 );
 
    abstract public function incrWithInit( $key, $exptime, $value = 1, $init = null, $flags = 0 );
 
    abstract public function getLastError();
 
    abstract public function clearLastError();
 
    abstract public function addBusyCallback( callable $workCallback );
 
    abstract public function makeKeyInternal( $keyspace, $components );
 
    abstract public function makeGlobalKey( $collection, ...$components );
 
    abstract public function makeKey( $collection, ...$components );
 
    public function isKeyGlobal( $key ) {
        return ( strncmp( $key, self::GLOBAL_PREFIX, self::GLOBAL_PREFIX_LEN ) === 0 );
    }
 
    public function getQoS( $flag ) {
        return $this->attrMap[$flag] ?? self::QOS_UNKNOWN;
    }
 
    public function getSegmentationSize() {
        return INF;
    }
 
    public function getSegmentedValueMaxSize() {
        return INF;
    }
 
    final protected function fieldHasFlags( $field, $flags ) {
        return ( ( $field & $flags ) === $flags );
    }
 
    final protected function mergeFlagMaps( array $bags ) {
        $map = [];
        foreach ( $bags as $bag ) {
            foreach ( $bag->attrMap as $attr => $rank ) {
                if ( isset( $map[$attr] ) ) {
                    $map[$attr] = min( $map[$attr], $rank );
                } else {
                    $map[$attr] = $rank;
                }
            }
        }
 
        return $map;
    }
 
    abstract public function setNewPreparedValues( array $valueByKey );
 
    public function registerWrapperInfoForStats(
        string $prefixComponent,
        string $statsGroup,
        callable $collectionCallback
    ) {
        $this->wrapperInfoByPrefix[$prefixComponent] = [
            self::WRAPPER_STATS_GROUP => $statsGroup,
            self::WRAPPER_COLLECTION_CALLBACK => $collectionCallback
        ];
    }
 
    final protected function genericKeyFromComponents( ...$components ) {
        if ( count( $components ) < 2 ) {
            throw new InvalidArgumentException( "Missing keyspace or collection name" );
        }
 
        $key = '';
        foreach ( $components as $component ) {
            if ( $key !== '' ) {
                $key .= ':';
            }
            // Escape delimiter (":") and escape ("%") characters
            $key .= strtr( $component, [ '%' => '%25', ':' => '%3A' ] );
        }
 
        return $key;
    }
 
    final protected function componentsFromGenericKey( $key ) {
        // Note that the order of each corresponding search/replace pair matters
        return str_replace( [ '%3A', '%25' ], [ ':', '%' ], explode( ':', $key ) );
    }
 
    abstract protected function convertGenericKey( $key );
 
    protected function proxyCall( $method, $arg0Sig, $resSig, array $genericArgs ) {
        // Get the corresponding store-specific cache keys...
        $storeArgs = $genericArgs;
        switch ( $arg0Sig ) {
            case self::ARG0_KEY:
                $storeArgs[0] = $this->convertGenericKey( $genericArgs[0] );
                break;
            case self::ARG0_KEYARR:
                foreach ( $genericArgs[0] as $i => $genericKey ) {
                    $storeArgs[0][$i] = $this->convertGenericKey( $genericKey );
                }
                break;
            case self::ARG0_KEYMAP:
                $storeArgs[0] = [];
                foreach ( $genericArgs[0] as $genericKey => $v ) {
                    $storeArgs[0][$this->convertGenericKey( $genericKey )] = $v;
                }
                break;
        }
 
        // Result of invoking the method with the corresponding store-specific cache keys
        $storeRes = $this->$method( ...$storeArgs );
 
        // Convert any store-specific cache keys in the result back to generic cache keys
        if ( $resSig === self::RES_KEYMAP ) {
            // Map of (store-specific cache key => generic cache key)
            $genericKeyByStoreKey = array_combine( $storeArgs[0], $genericArgs[0] );
 
            $genericRes = [];
            foreach ( $storeRes as $storeKey => $value ) {
                $genericRes[$genericKeyByStoreKey[$storeKey]] = $value;
            }
        } else {
            $genericRes = $storeRes;
        }
 
        return $genericRes;
    }
 
    protected function determineKeyPrefixForStats( $key ) {
        $firstComponent = substr( $key, 0, strcspn( $key, ':' ) );
 
        $wrapperInfo = $this->wrapperInfoByPrefix[$firstComponent] ?? null;
        if ( $wrapperInfo ) {
            // Key has the prefix of a cache wrapper class that wraps BagOStuff
            $collection = $wrapperInfo[self::WRAPPER_COLLECTION_CALLBACK]( $key );
            $statsGroup = $wrapperInfo[self::WRAPPER_STATS_GROUP];
        } else {
            // Key came directly from BagOStuff::makeKey() or BagOStuff::makeGlobalKey()
            // and thus has the format of "<scope>:<collection>[:<constant or variable>]..."
            $components = explode( ':', $key, 3 );
            // Handle legacy callers that fail to use the key building methods
            $collection = $components[1] ?? $components[0];
            $statsGroup = 'objectcache';
        }
 
        // Replace dots because they are special in StatsD (T232907)
        return $statsGroup . '.' . strtr( $collection, '.', '_' );
    }
 
    public function getCurrentTime() {
        return $this->wallClockOverride ?: microtime( true );
    }
 
    public function setMockTime( &$time ) {
        $this->wallClockOverride =& $time;
    }
}