MediaWiki  master
ParserCache Class Reference

Cache for ParserOutput objects corresponding to the latest page revisions. More...

Collaboration diagram for ParserCache:

Public Member Functions

 __construct (string $name, BagOStuff $cache, string $cacheEpoch, HookContainer $hookContainer, IBufferingStatsdDataFactory $stats, LoggerInterface $logger, $useJson=false)
 Setup a cache pathway with a given back-end storage mechanism. More...
 
 deleteOptionsKey (WikiPage $wikiPage)
 
 get (WikiPage $wikiPage, $popts, $useOutdated=false)
 Retrieve the ParserOutput from ParserCache. More...
 
 getCacheStorage ()
 Get the backend BagOStuff instance that powers the parser cache. More...
 
 getDirty (WikiPage $wikiPage, $popts)
 Retrieve the ParserOutput from ParserCache, even if it's outdated. More...
 
 getETag (WikiPage $wikiPage, $popts)
 Provides an E-Tag suitable for the whole page. More...
 
 getKey (WikiPage $wikiPage, $popts, $useOutdated=self::USE_ANYTHING)
 Generates a key for caching the given page considering the given parser options. More...
 
 getMetadata (WikiPage $wikiPage, int $staleConstraint=self::USE_ANYTHING)
 Returns the ParserCache metadata about the given page considering the given options. More...
 
 makeParserOutputKey (WikiPage $wikiPage, ParserOptions $options, array $usedOptions=null)
 Get a key that will be used by the ParserCache to store the content for a given page considering the given options and the array of used options. More...
 
 save (ParserOutput $parserOutput, WikiPage $wikiPage, $popts, $cacheTime=null, $revId=null)
 
 setJsonSupport (bool $readJson, bool $writeJson)
 

Public Attributes

const USE_CURRENT_ONLY = 0
 Constants for self::getKey() More...
 
const USE_EXPIRED = 1
 Use expired data if current data is unavailable. More...
 
const USE_OUTDATED = 2
 Use expired data or data from different revisions if current data is unavailable. More...
 

Private Member Functions

 encodeAsJson (CacheTime $obj, string $key)
 
 incrementStats (WikiPage $wikiPage, $metricSuffix)
 
 makeMetadataKey (WikiPage $wikiPage)
 
 restoreFromJson (string $jsonData, string $key)
 

Private Attributes

BagOStuff $cache
 
string $cacheEpoch
 Anything cached prior to this is invalidated. More...
 
HookRunner $hookRunner
 
LoggerInterface $logger
 
string $name
 The name of this ParserCache. More...
 
bool $readJson = false
 
IBufferingStatsdDataFactory $stats
 
bool $writeJson = false
 
const USE_ANYTHING = 3
 Use expired data and data from different revisions, and if all else fails vary on all variable options. More...
 

Detailed Description

Cache for ParserOutput objects corresponding to the latest page revisions.

The ParserCache is a two-tiered cache backed by BagOStuff which supports varying the stored content on the values of ParserOptions used during a page parse.

First tier is keyed by the page ID and stores ParserCacheMetadata, which contains information about cache expiration and the list of ParserOptions used during the parse of the page. For example, if only 'dateformat' and 'userlang' options were accessed by the parser when producing output for the page, array [ 'dateformat', 'userlang' ] will be stored in the metadata cache. This means none of the other existing options had any effect on the output.

The second tier of the cache contains ParserOutput objects. The key for the second tier is constructed from the page ID and values of those ParserOptions used during a page parse which affected the output. Upon cache lookup, the list of used option names is retrieved from tier 1 cache, and only the values of those options are hashed together with the page ID to produce a key, while the rest of the options are ignored. Following the example above where only [ 'dateformat', 'userlang' ] options changed the parser output for a page, the key will look like 'page_id!dateformat=default:userlang=ru'. Thus any cache lookup with dateformat=default and userlang=ru will hit the same cache entry regardless of the values of the rest of the options, since they were not accessed during a parse and thus did not change the output.

See also
ParserOutput::recordOption()
ParserOutput::getUsedOptions()
ParserOptions::allCacheVaryingOptions()

Definition at line 61 of file ParserCache.php.

Constructor & Destructor Documentation

◆ __construct()

ParserCache::__construct ( string  $name,
BagOStuff  $cache,
string  $cacheEpoch,
HookContainer  $hookContainer,
IBufferingStatsdDataFactory  $stats,
LoggerInterface  $logger,
  $useJson = false 
)

Setup a cache pathway with a given back-end storage mechanism.

This class use an invalidation strategy that is compatible with MultiWriteBagOStuff in async replication mode.

Parameters
string$name
BagOStuff$cache
string$cacheEpochAnything before this timestamp is invalidated
HookContainer$hookContainer
IBufferingStatsdDataFactory$stats
LoggerInterface$logger
bool$useJsonTemporary feature flag, remove before 1.36 is released.

Definition at line 131 of file ParserCache.php.

References $cache, $cacheEpoch, $logger, $name, and $stats.

Member Function Documentation

◆ deleteOptionsKey()

ParserCache::deleteOptionsKey ( WikiPage  $wikiPage)
Parameters
WikiPage$wikiPage
Since
1.28

Definition at line 154 of file ParserCache.php.

References makeMetadataKey().

◆ encodeAsJson()

ParserCache::encodeAsJson ( CacheTime  $obj,
string  $key 
)
private
Parameters
CacheTime$obj
string$key
Returns
string|null

Definition at line 640 of file ParserCache.php.

References FormatJson\detectNonSerializableData(), FormatJson\encode(), and CacheTime\jsonSerialize().

Referenced by save().

◆ get()

ParserCache::get ( WikiPage  $wikiPage,
  $popts,
  $useOutdated = false 
)

Retrieve the ParserOutput from ParserCache.

false if not found or outdated.

Parameters
WikiPage$wikiPage
ParserOptions$popts
bool$useOutdated(default false)
Returns
ParserOutput|bool False on failure

Definition at line 378 of file ParserCache.php.

References WikiPage\checkTouched(), WikiPage\getLatest(), getMetadata(), WikiPage\getTouched(), incrementStats(), makeParserOutputKey(), BagOStuff\READ_VERIFIED, and restoreFromJson().

◆ getCacheStorage()

ParserCache::getCacheStorage ( )

Get the backend BagOStuff instance that powers the parser cache.

Since
1.30

Definition at line 570 of file ParserCache.php.

References $cache.

◆ getDirty()

ParserCache::getDirty ( WikiPage  $wikiPage,
  $popts 
)

Retrieve the ParserOutput from ParserCache, even if it's outdated.

Parameters
WikiPage$wikiPage
ParserOptions$popts
Returns
ParserOutput|bool False on failure

Definition at line 185 of file ParserCache.php.

References true.

Referenced by RefreshLinksJob\getParserOutputFromCache().

◆ getETag()

ParserCache::getETag ( WikiPage  $wikiPage,
  $popts 
)

Provides an E-Tag suitable for the whole page.

Note that $wikiPage is just the main wikitext. The E-Tag has to be unique to the whole page, even if the article itself is the same, so it uses the complete set of user options. We don't want to use the preference of a different user on a message just because it wasn't used in $wikiPage. For example give a Chinese interface to a user with English preferences. That's why we take into account all user options. (r70809 CR)

Deprecated:
since 1.36
Parameters
WikiPage$wikiPage
ParserOptions$popts
Returns
string

Definition at line 173 of file ParserCache.php.

References WikiPage\getTouched(), makeParserOutputKey(), and wfDeprecated().

◆ getKey()

ParserCache::getKey ( WikiPage  $wikiPage,
  $popts,
  $useOutdated = self::USE_ANYTHING 
)

Generates a key for caching the given page considering the given parser options.

Note
Which parser options influence the cache key is controlled via ParserOutput::recordOption() or ParserOptions::addExtraKey().
Used by Article to provide a unique id for the PoolCounter. It would be preferable to have this code in get() instead of having Article looking in our internals.
Parameters
WikiPage$wikiPage
ParserOptions$popts
int | bool$useOutdatedOne of the USE constants. For backwards compatibility, boolean false is treated as USE_CURRENT_ONLY and boolean true is treated as USE_ANYTHING.
Returns
bool|mixed|string
Since
1.30 Changed $useOutdated to an int and added the non-boolean values
Deprecated:
1.36 Use ::getMetadata and ::makeParserOutputKey methods instead.

Definition at line 221 of file ParserCache.php.

References ParserOptions\allCacheVaryingOptions(), getMetadata(), makeParserOutputKey(), ParserOptions\newFromUser(), USE_ANYTHING, USE_CURRENT_ONLY, and wfDeprecated().

◆ getMetadata()

ParserCache::getMetadata ( WikiPage  $wikiPage,
int  $staleConstraint = self::USE_ANYTHING 
)

Returns the ParserCache metadata about the given page considering the given options.

Note
Which parser options influence the cache key is controlled via ParserOutput::recordOption() or ParserOptions::addExtraKey().
Parameters
WikiPage$wikiPage
int$staleConstraintone of the self::USE_ constants
Returns
ParserCacheMetadata|null
Since
1.36

Definition at line 260 of file ParserCache.php.

References WikiPage\getLatest(), WikiPage\getTouched(), incrementStats(), makeMetadataKey(), BagOStuff\READ_VERIFIED, and restoreFromJson().

Referenced by get(), and getKey().

◆ incrementStats()

ParserCache::incrementStats ( WikiPage  $wikiPage,
  $metricSuffix 
)
private
Parameters
WikiPage$wikiPage
string$metricSuffix

Definition at line 194 of file ParserCache.php.

References WikiPage\getContentModel().

Referenced by get(), and getMetadata().

◆ makeMetadataKey()

ParserCache::makeMetadataKey ( WikiPage  $wikiPage)
private
Parameters
WikiPage$wikiPage
Returns
string

Definition at line 331 of file ParserCache.php.

References WikiPage\getId().

Referenced by deleteOptionsKey(), getMetadata(), and save().

◆ makeParserOutputKey()

ParserCache::makeParserOutputKey ( WikiPage  $wikiPage,
ParserOptions  $options,
array  $usedOptions = null 
)

Get a key that will be used by the ParserCache to store the content for a given page considering the given options and the array of used options.

Warning
The exact format of the key is considered internal and is subject to change, thus should not be used as storage or long-term caching key. This is intended to be used for logging or keying something transient.
Parameters
WikiPage$wikiPage
ParserOptions$options
array | null$usedOptionsDefaults to all cache verying options.
Returns
string

Definition at line 351 of file ParserCache.php.

References $wgRequest, ParserOptions\allCacheVaryingOptions(), WikiPage\getId(), WikiPage\getTitle(), and ParserOptions\optionsHash().

Referenced by get(), getETag(), getKey(), and save().

◆ restoreFromJson()

ParserCache::restoreFromJson ( string  $jsonData,
string  $key 
)
private
Parameters
string$jsonData
string$key
Returns
CacheTime|null

Definition at line 591 of file ParserCache.php.

References $type, and FormatJson\decode().

Referenced by get(), and getMetadata().

◆ save()

ParserCache::save ( ParserOutput  $parserOutput,
WikiPage  $wikiPage,
  $popts,
  $cacheTime = null,
  $revId = null 
)

◆ setJsonSupport()

ParserCache::setJsonSupport ( bool  $readJson,
bool  $writeJson 
)
Note
setter for temporary feature flags, for use in testing.

Definition at line 580 of file ParserCache.php.

References $readJson, and $writeJson.

Member Data Documentation

◆ $cache

BagOStuff ParserCache::$cache
private

Definition at line 87 of file ParserCache.php.

Referenced by __construct(), and getCacheStorage().

◆ $cacheEpoch

string ParserCache::$cacheEpoch
private

Anything cached prior to this is invalidated.

Definition at line 94 of file ParserCache.php.

Referenced by __construct().

◆ $hookRunner

HookRunner ParserCache::$hookRunner
private

Definition at line 97 of file ParserCache.php.

◆ $logger

LoggerInterface ParserCache::$logger
private

Definition at line 103 of file ParserCache.php.

Referenced by __construct().

◆ $name

string ParserCache::$name
private

The name of this ParserCache.

Used as a root of the cache key.

Definition at line 84 of file ParserCache.php.

Referenced by __construct().

◆ $readJson

bool ParserCache::$readJson = false
private
Note
Temporary feature flag, remove before 1.36 is released.

Definition at line 115 of file ParserCache.php.

Referenced by setJsonSupport().

◆ $stats

IBufferingStatsdDataFactory ParserCache::$stats
private

Definition at line 100 of file ParserCache.php.

Referenced by __construct().

◆ $writeJson

bool ParserCache::$writeJson = false
private
Note
Temporary feature flag, remove before 1.36 is released.

Definition at line 109 of file ParserCache.php.

Referenced by setJsonSupport().

◆ USE_ANYTHING

const ParserCache::USE_ANYTHING = 3
private

Use expired data and data from different revisions, and if all else fails vary on all variable options.

Definition at line 81 of file ParserCache.php.

Referenced by getKey().

◆ USE_CURRENT_ONLY

const ParserCache::USE_CURRENT_ONLY = 0

Constants for self::getKey()

Since
1.30
1.36 the constants were made public Use only current data

Definition at line 69 of file ParserCache.php.

Referenced by getKey().

◆ USE_EXPIRED

const ParserCache::USE_EXPIRED = 1

Use expired data if current data is unavailable.

Definition at line 72 of file ParserCache.php.

◆ USE_OUTDATED

const ParserCache::USE_OUTDATED = 2

Use expired data or data from different revisions if current data is unavailable.

Definition at line 75 of file ParserCache.php.


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