MediaWiki  master
MediaWiki\Settings\Cache\CachedSource Class Reference

Provides a caching layer for a CacheableSource. More...

Inheritance diagram for MediaWiki\Settings\Cache\CachedSource:
Collaboration diagram for MediaWiki\Settings\Cache\CachedSource:

Public Member Functions

 __construct (BagOStuff $cache, CacheableSource $source)
 Constructs a new CachedSource using an instantiated cache and CacheableSource. More...
 
 __toString ()
 Returns the string representation of the encapsulated source. More...
 
 load ()
 Queries cache for source contents and performs loading/caching of the source contents on miss. More...
 
 locateInclude (string $location)
 This method defines how a relative reference to the location of another settings source is interpreted. More...
 

Private Member Functions

 expiresEarly (array $item, float $weight)
 Decide whether the cached source should be expired early according to a probabilistic calculation that becomes more likely as the normal expiry approaches. More...
 
 isExpired ( $item)
 Whether the given cache item is considered expired, in other words: More...
 
 isValidHit ( $item)
 Whether the given cache item is considered a cache hit, in other words: More...
 
 loadAndCache (string $key)
 Loads the source and caches the result. More...
 
 loadWithMetadata ()
 Wraps cached source with the metadata needed to perform probabilistic early expiration to help mitigate cache stampedes. More...
 

Private Attributes

BagOStuff $cache
 
CacheableSource $source
 
const TIMEOUT = 2
 Cached source generation timeout (in seconds). More...
 

Detailed Description

Provides a caching layer for a CacheableSource.

Since
1.38
Todo:
mark as stable before the 1.38 release

Definition at line 17 of file CachedSource.php.

Constructor & Destructor Documentation

◆ __construct()

MediaWiki\Settings\Cache\CachedSource::__construct ( BagOStuff  $cache,
CacheableSource  $source 
)

Constructs a new CachedSource using an instantiated cache and CacheableSource.

Parameters
BagOStuff$cache
CacheableSource$source

Definition at line 36 of file CachedSource.php.

References MediaWiki\Settings\Cache\CachedSource\$cache, and MediaWiki\Settings\Cache\CachedSource\$source.

Member Function Documentation

◆ __toString()

MediaWiki\Settings\Cache\CachedSource::__toString ( )

Returns the string representation of the encapsulated source.

Returns
string

Definition at line 119 of file CachedSource.php.

◆ expiresEarly()

MediaWiki\Settings\Cache\CachedSource::expiresEarly ( array  $item,
float  $weight 
)
private

Decide whether the cached source should be expired early according to a probabilistic calculation that becomes more likely as the normal expiry approaches.

In other words, we're going to pretend we're a bit further into the future than we are so that we might expire and regenerate the cached settings before other threads attempt to the do the same. The number of threads that will pretend to be far into the future (and thus will concurrently reload/cache the settings) will most probably be so exponentially fewer than the number of threads pretending to be near into the future that it will approach optimal stampede protection without the use of an exclusive lock.

Parameters
array$itemCached source with expiry metadata.
float$weightCoefficient used to increase/decrease the likelihood of early expiration.

bool

Definition at line 176 of file CachedSource.php.

◆ isExpired()

MediaWiki\Settings\Cache\CachedSource::isExpired (   $item)
private

Whether the given cache item is considered expired, in other words:

  • its expiry timestamp has passed
  • it is deemed to expire early so as to mitigate cache stampedes
Parameters
array$itemCache item.
Returns
bool

Definition at line 149 of file CachedSource.php.

Referenced by MediaWiki\Settings\Cache\CachedSource\load().

◆ isValidHit()

MediaWiki\Settings\Cache\CachedSource::isValidHit (   $item)
private

Whether the given cache item is considered a cache hit, in other words:

  • it is not a falsey value
  • it has the correct type and structure for this cache implementation
Parameters
mixed$itemCache item.
Returns
bool

Definition at line 132 of file CachedSource.php.

Referenced by MediaWiki\Settings\Cache\CachedSource\load().

◆ load()

MediaWiki\Settings\Cache\CachedSource::load ( )

Queries cache for source contents and performs loading/caching of the source contents on miss.

If the load fails but the source implements {} as true, stale results may be returned if still present in the cache store. array

Implements MediaWiki\Settings\Source\SettingsSource.

Definition at line 54 of file CachedSource.php.

References MediaWiki\Settings\Cache\CachedSource\isExpired(), and MediaWiki\Settings\Cache\CachedSource\isValidHit().

◆ loadAndCache()

MediaWiki\Settings\Cache\CachedSource::loadAndCache ( string  $key)
private

Loads the source and caches the result.

Parameters
string$key
Returns
array

Definition at line 199 of file CachedSource.php.

◆ loadWithMetadata()

MediaWiki\Settings\Cache\CachedSource::loadWithMetadata ( )
private

Wraps cached source with the metadata needed to perform probabilistic early expiration to help mitigate cache stampedes.

Returns
array

Definition at line 216 of file CachedSource.php.

◆ locateInclude()

MediaWiki\Settings\Cache\CachedSource::locateInclude ( string  $location)

This method defines how a relative reference to the location of another settings source is interpreted.

It tries to make $location absolute by interpreting it as relative to the location of the SettingsSource it originates from.

Implementation are "best effort". If a location cannot be made absolute, it may be returned as-is. Implementations are also free to throw a SettingsBuilderException to indicate that the given include location is not supported in this context.

Parameters
string$location
Returns
string
Exceptions
SettingsBuilderExceptionif the given location cannot be used as an include by the current source.

Implements MediaWiki\Settings\Source\SettingsIncludeLocator.

Definition at line 228 of file CachedSource.php.

Member Data Documentation

◆ $cache

BagOStuff MediaWiki\Settings\Cache\CachedSource::$cache
private

Definition at line 24 of file CachedSource.php.

Referenced by MediaWiki\Settings\Cache\CachedSource\__construct().

◆ $source

CacheableSource MediaWiki\Settings\Cache\CachedSource::$source
private

Definition at line 27 of file CachedSource.php.

Referenced by MediaWiki\Settings\Cache\CachedSource\__construct().

◆ TIMEOUT

const MediaWiki\Settings\Cache\CachedSource::TIMEOUT = 2
private

Cached source generation timeout (in seconds).

Definition at line 21 of file CachedSource.php.


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