MapCacheLRU.php

Go to the documentation of this file.

<?php
namespace Wikimedia\MapCacheLRU;
 
use InvalidArgumentException;
use UnexpectedValueException;
use Wikimedia\LightweightObjectStore\ExpirationAwareness;
 
class MapCacheLRU implements ExpirationAwareness {
    private $cache = [];
    private $timestamps = [];
    private $epoch;
 
    private $maxCacheKeys;
 
    private $wallClockOverride;
 
    private const RANK_TOP = 1.0;
 
    private const SIMPLE = 0;
    private const FIELDS = 1;
 
    public function __construct( int $maxKeys ) {
        if ( $maxKeys <= 0 ) {
            throw new InvalidArgumentException( '$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 ) {
            $evictKey = array_key_first( $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.' );
        }
        return array_key_exists( $key, $this->cache )
            && (
                // Optimization: Avoid expensive getAge/getCurrentTime for common case (T275673)
                $maxAge === INF
                || $maxAge <= 0
                || $this->getKeyAge( $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 );
 
            if ( !is_array( $this->cache[$key] ) ) {
                $type = get_debug_type( $this->cache[$key] );
                throw new UnexpectedValueException( "Cannot add field to non-array value ('$key' is $type)" );
            }
        } else {
            $this->set( $key, [], $initRank );
        }
 
        if ( !is_string( $field ) && !is_int( $field ) ) {
            throw new UnexpectedValueException(
                __METHOD__ . ": invalid field for '$key'; must be string or integer." );
        }
 
        $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." );
        }
        return is_array( $value )
            && array_key_exists( $field, $value )
            && (
                $maxAge === INF
                || $maxAge <= 0
                || $this->getKeyFieldAge( $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 = $callback();
            if ( $value !== false ) {
                $this->set( $key, $value, $rank );
            }
        }
 
        return $value;
    }
 
    public function makeKey( ...$components ) {
        // Based on BagOStuff::makeKeyInternal, except without a required
        // $keygroup prefix. While MapCacheLRU can and is used as cache for
        // multiple groups of keys, it is equally common for the instance itself
        // to represent a single group, and thus have keys where the first component
        // can directly be a user-controlled variable.
        $key = '';
        foreach ( $components as $i => $component ) {
            if ( $i > 0 ) {
                $key .= ':';
            }
            $key .= strtr( $component, [ '%' => '%25', ':' => '%3A' ] );
        }
        return $key;
    }
 
    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( int $maxKeys ) {
        if ( $maxKeys <= 0 ) {
            throw new InvalidArgumentException( '$maxKeys must be above zero' );
        }
 
        $this->maxCacheKeys = $maxKeys;
        while ( count( $this->cache ) > $this->maxCacheKeys ) {
            $evictKey = array_key_first( $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 getKeyAge( $key ) {
        $mtime = $this->timestamps[$key][self::SIMPLE] ?? $this->epoch;
 
        return ( $this->getCurrentTime() - $mtime );
    }
 
    private function getKeyFieldAge( $key, $field ) {
        $mtime = $this->timestamps[$key][self::FIELDS][$field] ?? $this->epoch;
 
        return ( $this->getCurrentTime() - $mtime );
    }
 
    public function __serialize() {
        return [
            'entries' => $this->cache,
            'timestamps' => $this->timestamps,
            'maxCacheKeys' => $this->maxCacheKeys,
        ];
    }
 
    public function __unserialize( $data ) {
        $this->cache = $data['entries'] ?? [];
        $this->timestamps = $data['timestamps'] ?? [];
        // Fallback needed for serializations prior to T218511
        $this->maxCacheKeys = $data['maxCacheKeys'] ?? ( count( $this->cache ) + 1 );
        $this->epoch = $this->getCurrentTime();
    }
 
    protected function getCurrentTime() {
        return $this->wallClockOverride ?: microtime( true );
    }
 
    public function setMockTime( &$time ) {
        $this->wallClockOverride =& $time;
    }
}
 
class_alias( MapCacheLRU::class, 'MapCacheLRU' );