MediaWiki  master
MapCacheLRU Class Reference

Handles a simple LRU key/value map with a maximum number of entries. More...

Inheritance diagram for MapCacheLRU:
Collaboration diagram for MapCacheLRU:

Public Member Functions

 __construct ( $maxKeys)
 
 clear ( $keys=null)
 Clear one or several cache entries, or all cache entries. More...
 
 get ( $key, $maxAge=0.0)
 Get the value for a key. More...
 
 getAllKeys ()
 
 getField ( $key, $field, $maxAge=0.0)
 
 getMaxSize ()
 Get the maximum number of keys allowed. More...
 
 getWithSetCallback ( $key, callable $callback, $rank=self::RANK_TOP, $maxAge=0.0)
 Get an item with the given key, producing and setting it if not found. More...
 
 has ( $key, $maxAge=0.0)
 Check if a key exists. More...
 
 hasField ( $key, $field, $maxAge=0.0)
 
 serialize ()
 
 set ( $key, $value, $rank=self::RANK_TOP)
 Set a key/value pair. More...
 
 setField ( $key, $field, $value, $initRank=self::RANK_TOP)
 
 setMaxSize ( $maxKeys)
 Resize the maximum number of cache entries, removing older entries as needed. More...
 
 setMockTime (&$time)
 
 toArray ()
 
 unserialize ( $serialized)
 

Static Public Member Functions

static newFromArray (array $values, $maxKeys)
 

Public Attributes

const RANK_TOP = 1.0
 
- Public Attributes inherited from IExpiringStore
const ATTR_EMULATION = 1
 
const ATTR_SYNCWRITES = 2
 
const QOS_EMULATION_SQL = 1
 
const QOS_SYNCWRITES_BE = 2
 
const QOS_SYNCWRITES_NONE = 1
 
const QOS_SYNCWRITES_QC = 3
 
const QOS_SYNCWRITES_SS = 4
 
const QOS_UNKNOWN = INF
 
const TTL_DAY = 86400
 
const TTL_HOUR = 3600
 
const TTL_INDEFINITE = 0
 
const TTL_MINUTE = 60
 
const TTL_MONTH = 2592000
 
const TTL_PROC_LONG = 30
 
const TTL_PROC_SHORT = 3
 
const TTL_SECOND = 1
 
const TTL_WEEK = 604800
 
const TTL_YEAR = 31536000
 

Protected Member Functions

 getCurrentTime ()
 

Private Member Functions

 getAge ( $key, $field=null)
 
 ping ( $key)
 Push an entry to the top of the cache. More...
 

Private Attributes

array $cache = []
 Map of (key => value) More...
 
float $epoch
 Default entry timestamp if not specified. More...
 
int $maxCacheKeys
 Max number of entries. More...
 
array $timestamps = []
 Map of (key => (UNIX timestamp, (field => UNIX timestamp))) More...
 
float null $wallClockOverride
 

Detailed Description

Handles a simple LRU key/value map with a maximum number of entries.

The last-modification timestamp of entries is internally tracked so that callers can specify the maximum acceptable age of entries in calls to the has() method. As a convenience, the hasField(), getField(), and setField() methods can be used for entries that are field/value maps themselves; such fields will have their own internally tracked last-modification timestamp.

See also
ProcessCacheLRU
Since
1.23

Definition at line 37 of file MapCacheLRU.php.

Constructor & Destructor Documentation

◆ __construct()

MapCacheLRU::__construct (   $maxKeys)
Parameters
int$maxKeysMaximum number of entries allowed (min 1)
Exceptions
ExceptionWhen $maxKeys is not an int or not above zero

Definition at line 62 of file MapCacheLRU.php.

References getCurrentTime().

Member Function Documentation

◆ clear()

MapCacheLRU::clear (   $keys = null)

Clear one or several cache entries, or all cache entries.

Parameters
string | array | null$keys
Returns
void

Definition at line 277 of file MapCacheLRU.php.

References $keys, array(), as, and cache.

Referenced by Title\clearCaches().

◆ get()

MapCacheLRU::get (   $key,
  $maxAge = 0.0 
)

Get the value for a key.

This returns null if the key is not set. If the item is already set, it will be pushed to the top of the cache.

Parameters
string$key
float$maxAgeIgnore items older than this many seconds optional
Returns
mixed Returns null if the key was not found or is older than $maxAge

Definition at line 163 of file MapCacheLRU.php.

References cache, has(), and ping().

Referenced by MessageCache\load(), and Title\newFromTextThrow().

◆ getAge()

MapCacheLRU::getAge (   $key,
  $field = null 
)
private
Parameters
string | int$key
string | int | null$field[optional]
Returns
float UNIX timestamp; the age of the given entry or entry field

Definition at line 336 of file MapCacheLRU.php.

References $epoch, and getCurrentTime().

Referenced by has(), and hasField().

◆ getAllKeys()

MapCacheLRU::getAllKeys ( )
Returns
array
Since
1.25

Definition at line 240 of file MapCacheLRU.php.

References cache.

◆ getCurrentTime()

MapCacheLRU::getCurrentTime ( )
protected
Returns
float UNIX timestamp

Definition at line 364 of file MapCacheLRU.php.

Referenced by __construct(), getAge(), set(), setField(), and unserialize().

◆ getField()

MapCacheLRU::getField (   $key,
  $field,
  $maxAge = 0.0 
)
Parameters
string | int$key
string | int$field
float$maxAgeIgnore items older than this many seconds optional
Returns
mixed Returns null if the key was not found or is older than $maxAge

Definition at line 228 of file MapCacheLRU.php.

References cache, and hasField().

◆ getMaxSize()

MapCacheLRU::getMaxSize ( )

Get the maximum number of keys allowed.

Returns
int
Since
1.32

Definition at line 295 of file MapCacheLRU.php.

References $maxCacheKeys.

◆ getWithSetCallback()

MapCacheLRU::getWithSetCallback (   $key,
callable  $callback,
  $rank = self::RANK_TOP,
  $maxAge = 0.0 
)

Get an item with the given key, producing and setting it if not found.

If the callback returns false, then nothing is stored.

Since
1.28
Parameters
string$key
callable$callbackCallback that will produce the value
float$rankBottom fraction of the list where keys start off [Default: 1.0]
float$maxAgeIgnore items older than this many seconds Default: 0.0
Returns
mixed The cached value if found or the result of $callback otherwise

Definition at line 256 of file MapCacheLRU.php.

References $value, and has().

◆ has()

MapCacheLRU::has (   $key,
  $maxAge = 0.0 
)

Check if a key exists.

Parameters
string$key
float$maxAgeIgnore items older than this many seconds optional
Returns
bool

Definition at line 141 of file MapCacheLRU.php.

References cache, and getAge().

Referenced by get(), getWithSetCallback(), set(), and setField().

◆ hasField()

MapCacheLRU::hasField (   $key,
  $field,
  $maxAge = 0.0 
)
Parameters
string | int$key
string | int$field
float$maxAgeIgnore items older than this many seconds optional
Returns
bool

Definition at line 207 of file MapCacheLRU.php.

References getAge().

Referenced by getField().

◆ newFromArray()

static MapCacheLRU::newFromArray ( array  $values,
  $maxKeys 
)
static
Parameters
array$valuesKey/value map in order of increasingly recent access
int$maxKeys
Returns
MapCacheLRU
Since
1.30

Definition at line 77 of file MapCacheLRU.php.

Referenced by MapCacheLRUTest\testArrayConversion(), MapCacheLRUTest\testExpiry(), MapCacheLRUTest\testFields(), MapCacheLRUTest\testInvalidKeys(), MapCacheLRUTest\testLRU(), and MapCacheLRUTest\testSerialize().

◆ ping()

MapCacheLRU::ping (   $key)
private

Push an entry to the top of the cache.

Parameters
string$key

Definition at line 325 of file MapCacheLRU.php.

References cache.

Referenced by get(), set(), and setField().

◆ serialize()

MapCacheLRU::serialize ( )

Definition at line 346 of file MapCacheLRU.php.

References cache.

◆ set()

MapCacheLRU::set (   $key,
  $value,
  $rank = self::RANK_TOP 
)

Set a key/value pair.

This will prune the cache if it gets too large based on LRU. If the item is already set, it will be pushed to the top of the cache.

To reduce evictions due to one-off use of many new keys, $rank can be set to have keys start at the top of a bottom fraction of the list. A value of 3/8 means values start at the top of the bottom 3/8s of the list and are moved to the top of the list when accessed a second time.

Parameters
string$key
mixed$value
float$rankBottom fraction of the list where keys start off [Default: 1.0]
Returns
void

Definition at line 109 of file MapCacheLRU.php.

References $value, cache, getCurrentTime(), has(), key, and ping().

Referenced by Title\newFromTextThrow().

◆ setField()

MapCacheLRU::setField (   $key,
  $field,
  $value,
  $initRank = self::RANK_TOP 
)
Parameters
string | int$key
string | int$field
mixed$value
float$initRank

Definition at line 179 of file MapCacheLRU.php.

References $type, $value, cache, getCurrentTime(), has(), and ping().

◆ setMaxSize()

MapCacheLRU::setMaxSize (   $maxKeys)

Resize the maximum number of cache entries, removing older entries as needed.

Parameters
int$maxKeysMaximum number of entries allowed (min 1)
Returns
void
Exceptions
ExceptionWhen $maxKeys is not an int or not above zero
Since
1.32

Definition at line 307 of file MapCacheLRU.php.

References cache, and key.

◆ setMockTime()

MapCacheLRU::setMockTime ( $time)
Parameters
float | null&$timeMock UNIX timestamp for testing

Definition at line 372 of file MapCacheLRU.php.

References $time.

◆ toArray()

MapCacheLRU::toArray ( )
Returns
array Key/value map in order of increasingly recent access
Since
1.30

Definition at line 90 of file MapCacheLRU.php.

References $cache.

◆ unserialize()

MapCacheLRU::unserialize (   $serialized)

Definition at line 353 of file MapCacheLRU.php.

References $serialized, cache, and getCurrentTime().

Member Data Documentation

◆ $cache

array MapCacheLRU::$cache = []
private

Map of (key => value)

Definition at line 39 of file MapCacheLRU.php.

Referenced by toArray().

◆ $epoch

float MapCacheLRU::$epoch
private

Default entry timestamp if not specified.

Definition at line 43 of file MapCacheLRU.php.

Referenced by getAge().

◆ $maxCacheKeys

int MapCacheLRU::$maxCacheKeys
private

Max number of entries.

Definition at line 46 of file MapCacheLRU.php.

Referenced by getMaxSize().

◆ $timestamps

array MapCacheLRU::$timestamps = []
private

Map of (key => (UNIX timestamp, (field => UNIX timestamp)))

Definition at line 41 of file MapCacheLRU.php.

◆ $wallClockOverride

float null MapCacheLRU::$wallClockOverride
private

Definition at line 49 of file MapCacheLRU.php.

◆ RANK_TOP

const MapCacheLRU::RANK_TOP = 1.0

Definition at line 51 of file MapCacheLRU.php.


The documentation for this class was generated from the following file: