MapCacheLRU.php

Go to the documentation of this file.

<?php
use Wikimedia\Assert\Assert;
 
class MapCacheLRU implements IExpiringStore, Serializable {
    private $cache = [];
    private $timestamps = [];
    private $epoch;
 
    private $maxCacheKeys;
 
    private $wallClockOverride;
 
    const RANK_TOP = 1.0;
 
    const SIMPLE = 0;
    const FIELDS = 1;
 
    public function __construct( $maxKeys ) {
        Assert::parameterType( 'integer', $maxKeys, '$maxKeys' );
        Assert::parameter( $maxKeys > 0, '$maxKeys', 'must be above zero' );
 
        $this->maxCacheKeys = $maxKeys;
        // Use the current time as the default "as of" timestamp of entries
        $this->epoch = $this->getCurrentTime();
    }
 
    public static function newFromArray( array $values, $maxKeys ) {
        $mapCache = new self( $maxKeys );
        $mapCache->cache = ( count( $values ) > $maxKeys )
            ? array_slice( $values, -$maxKeys, null, true )
            : $values;
 
        return $mapCache;
    }
 
    public function toArray() {
        return $this->cache;
    }
 
    public function set( $key, $value, $rank = self::RANK_TOP ) {
        if ( $this->has( $key ) ) {
            $this->ping( $key );
        } elseif ( count( $this->cache ) >= $this->maxCacheKeys ) {
            reset( $this->cache );
            $evictKey = key( $this->cache );
            unset( $this->cache[$evictKey] );
            unset( $this->timestamps[$evictKey] );
        }
 
        if ( $rank < 1.0 && $rank > 0 ) {
            $offset = intval( $rank * count( $this->cache ) );
            $this->cache = array_slice( $this->cache, 0, $offset, true )
                + [ $key => $value ]
                + array_slice( $this->cache, $offset, null, true );
        } else {
            $this->cache[$key] = $value;
        }
 
        $this->timestamps[$key] = [
            self::SIMPLE => $this->getCurrentTime(),
            self::FIELDS => []
        ];
    }
 
    public function has( $key, $maxAge = INF ) {
        if ( !is_int( $key ) && !is_string( $key ) ) {
            throw new UnexpectedValueException(
                __METHOD__ . ': invalid key; must be string or integer.' );
        }
 
        if ( !array_key_exists( $key, $this->cache ) ) {
            return false;
        }
 
        return ( $maxAge <= 0 || $this->getAge( $key ) <= $maxAge );
    }
 
    public function get( $key, $maxAge = INF, $default = null ) {
        if ( !$this->has( $key, $maxAge ) ) {
            return $default;
        }
 
        $this->ping( $key );
 
        return $this->cache[$key];
    }
 
    public function setField( $key, $field, $value, $initRank = self::RANK_TOP ) {
        if ( $this->has( $key ) ) {
            $this->ping( $key );
        } else {
            $this->set( $key, [], $initRank );
        }
 
        if ( !is_int( $field ) && !is_string( $field ) ) {
            throw new UnexpectedValueException(
                __METHOD__ . ": invalid field for '$key'; must be string or integer." );
        }
 
        if ( !is_array( $this->cache[$key] ) ) {
            $type = gettype( $this->cache[$key] );
 
            throw new UnexpectedValueException( "The value of '$key' ($type) is not an array." );
        }
 
        $this->cache[$key][$field] = $value;
        $this->timestamps[$key][self::FIELDS][$field] = $this->getCurrentTime();
    }
 
    public function hasField( $key, $field, $maxAge = INF ) {
        $value = $this->get( $key );
 
        if ( !is_int( $field ) && !is_string( $field ) ) {
            throw new UnexpectedValueException(
                __METHOD__ . ": invalid field for '$key'; must be string or integer." );
        }
 
        if ( !is_array( $value ) || !array_key_exists( $field, $value ) ) {
            return false;
        }
 
        return ( $maxAge <= 0 || $this->getAge( $key, $field ) <= $maxAge );
    }
 
    public function getField( $key, $field, $maxAge = INF ) {
        if ( !$this->hasField( $key, $field, $maxAge ) ) {
            return null;
        }
 
        return $this->cache[$key][$field];
    }
 
    public function getAllKeys() {
        return array_keys( $this->cache );
    }
 
    public function getWithSetCallback(
        $key, callable $callback, $rank = self::RANK_TOP, $maxAge = INF
    ) {
        if ( $this->has( $key, $maxAge ) ) {
            $value = $this->get( $key );
        } else {
            $value = call_user_func( $callback );
            if ( $value !== false ) {
                $this->set( $key, $value, $rank );
            }
        }
 
        return $value;
    }
 
    public function clear( $keys = null ) {
        if ( func_num_args() == 0 ) {
            $this->cache = [];
            $this->timestamps = [];
        } else {
            foreach ( (array)$keys as $key ) {
                unset( $this->cache[$key] );
                unset( $this->timestamps[$key] );
            }
        }
    }
 
    public function getMaxSize() {
        return $this->maxCacheKeys;
    }
 
    public function setMaxSize( $maxKeys ) {
        Assert::parameterType( 'integer', $maxKeys, '$maxKeys' );
        Assert::parameter( $maxKeys > 0, '$maxKeys', 'must be above zero' );
 
        $this->maxCacheKeys = $maxKeys;
        while ( count( $this->cache ) > $this->maxCacheKeys ) {
            reset( $this->cache );
            $evictKey = key( $this->cache );
            unset( $this->cache[$evictKey] );
            unset( $this->timestamps[$evictKey] );
        }
    }
 
    private function ping( $key ) {
        $item = $this->cache[$key];
        unset( $this->cache[$key] );
        $this->cache[$key] = $item;
    }
 
    private function getAge( $key, $field = null ) {
        if ( $field !== null ) {
            $mtime = $this->timestamps[$key][self::FIELDS][$field] ?? $this->epoch;
        } else {
            $mtime = $this->timestamps[$key][self::SIMPLE] ?? $this->epoch;
        }
 
        return ( $this->getCurrentTime() - $mtime );
    }
 
    public function serialize() {
        return serialize( [
            'entries' => $this->cache,
            'timestamps' => $this->timestamps
        ] );
    }
 
    public function unserialize( $serialized ) {
        $data = unserialize( $serialized );
        $this->cache = $data['entries'] ?? [];
        $this->timestamps = $data['timestamps'] ?? [];
        $this->epoch = $this->getCurrentTime();
    }
 
    protected function getCurrentTime() {
        return $this->wallClockOverride ?: microtime( true );
    }
 
    public function setMockTime( &$time ) {
        $this->wallClockOverride =& $time;
    }
}