BagOStuff.php

Go to the documentation of this file.

<?php
use Psr\Log\LoggerAwareInterface;
use Psr\Log\LoggerInterface;
use Psr\Log\NullLogger;
use Wikimedia\ScopedCallback;

abstract class BagOStuff implements IExpiringStore, IStoreKeyEncoder, LoggerAwareInterface {
    protected $logger;

    protected $asyncHandler;
    protected $attrMap = [];

    protected $debugMode = false;

    private $wallClockOverride;

    const READ_LATEST = 1; // if supported, avoid reading stale data due to replication
    const READ_VERIFIED = 2; // promise that the caller handles detection of staleness
    const WRITE_SYNC = 4; // if supported, block until the write is fully replicated
    const WRITE_CACHE_ONLY = 8; // only change state of the in-memory cache
    const WRITE_ALLOW_SEGMENTS = 16; // allow partitioning of the value if it is large
    const WRITE_PRUNE_SEGMENTS = 32; // delete all the segments if the value is partitioned
    const WRITE_BACKGROUND = 64; // if supported, do not block on completion until the next read

    public function __construct( array $params = [] ) {
        $this->setLogger( $params['logger'] ?? new NullLogger() );
        $this->asyncHandler = $params['asyncHandler'] ?? null;
    }

    public function setLogger( LoggerInterface $logger ) {
        $this->logger = $logger;
    }

    public function setDebug( $enabled ) {
        $this->debugMode = $enabled;
    }

    final public function getWithSetCallback( $key, $ttl, $callback, $flags = 0 ) {
        $value = $this->get( $key, $flags );

        if ( $value === false ) {
            $value = $callback( $ttl );
            if ( $value !== false && $ttl >= 0 ) {
                $this->set( $key, $value, $ttl, $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 $data, $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, $args );

    abstract public function makeGlobalKey( $class, ...$components );

    abstract public function makeKey( $class, ...$components );

    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;
    }

    public function getCurrentTime() {
        return $this->wallClockOverride ?: microtime( true );
    }

    public function setMockTime( &$time ) {
        $this->wallClockOverride =& $time;
    }
}