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

Collaboration diagram for ParserCache:

[legend]

Public Member Functions
	__construct (string $name, BagOStuff $cache, string $cacheEpoch, HookContainer $hookContainer, JsonCodec $jsonCodec, IBufferingStatsdDataFactory $stats, LoggerInterface $logger, TitleFactory $titleFactory, WikiPageFactory $wikiPageFactory, $useJson=false)
	Setup a cache pathway with a given back-end storage mechanism. More...

	deleteOptionsKey (PageRecord $page)

	get (PageRecord $page, $popts, $useOutdated=false)
	Retrieve the ParserOutput from ParserCache. More...

	getCacheStorage ()
	Get the backend BagOStuff instance that powers the parser cache. More...

	getDirty (PageRecord $page, $popts)
	Retrieve the ParserOutput from ParserCache, even if it's outdated. More...

	getMetadata (PageRecord $page, int $staleConstraint=self::USE_ANYTHING)
	Returns the ParserCache metadata about the given page considering the given options. More...

	makeParserOutputKey (PageRecord $page, 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, PageRecord $page, $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
	checkExpired (CacheTime $entry, PageRecord $page, int $staleConstraint, string $cacheTier)
	Check if $entry expired for $page given the $staleConstraint when fetching from $cacheTier. More...

	checkOutdated (CacheTime $entry, PageRecord $page, int $staleConstraint, string $cacheTier)
	Check if $entry belongs to the latest revision of $page given $staleConstraint when fetched from $cacheTier. More...

	encodeAsJson (CacheTime $obj, string $key)

	incrementStats (PageRecord $page, $metricSuffix)

	makeMetadataKey (PageRecord $page)

	restoreFromJson (string $jsonData, string $key, string $expectedClass)

Private Attributes
BagOStuff	$cache

string	$cacheEpoch
	Anything cached prior to this is invalidated. More...

HookRunner	$hookRunner

JsonCodec	$jsonCodec

LoggerInterface	$logger

BagOStuff	$metadataProcCache
	small in-process cache to store metadata. More...

string	$name
	The name of this ParserCache. More...

bool	$readJson = false

IBufferingStatsdDataFactory	$stats

TitleFactory	$titleFactory

WikiPageFactory	$wikiPageFactory

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 63 of file ParserCache.php.

Constructor & Destructor Documentation

◆ __construct()

ParserCache::__construct	(	string	$name,
		BagOStuff	$cache,
		string	$cacheEpoch,
		HookContainer	$hookContainer,
		JsonCodec	$jsonCodec,
		IBufferingStatsdDataFactory	$stats,
		LoggerInterface	$logger,
		TitleFactory	$titleFactory,
		WikiPageFactory	$wikiPageFactory,
			$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	$cacheEpoch	Anything before this timestamp is invalidated
HookContainer	$hookContainer
JsonCodec	$jsonCodec
IBufferingStatsdDataFactory	$stats
LoggerInterface	$logger
TitleFactory	$titleFactory
WikiPageFactory	$wikiPageFactory
bool	$useJson	Temporary feature flag, remove before 1.36 is released.

Definition at line 153 of file ParserCache.php.

References $cache, $cacheEpoch, $jsonCodec, $logger, $name, $stats, $titleFactory, and $wikiPageFactory.

Member Function Documentation

◆ checkExpired()

ParserCache::checkExpired	(	CacheTime	$entry,
		PageRecord	$page,
		int	$staleConstraint,
		string	$cacheTier
	)

private

Check if $entry expired for $page given the $staleConstraint when fetching from $cacheTier.

Parameters

CacheTime	$entry
PageRecord	$page
int	$staleConstraint	One of USE_* constants.
string	$cacheTier

Returns: bool

Definition at line 540 of file ParserCache.php.

References CacheTime\getCacheTime(), Page\PageRecord\getTouched(), and incrementStats().

Referenced by get(), and getMetadata().

◆ checkOutdated()

ParserCache::checkOutdated	(	CacheTime	$entry,
		PageRecord	$page,
		int	$staleConstraint,
		string	$cacheTier
	)

private

Check if $entry belongs to the latest revision of $page given $staleConstraint when fetched from $cacheTier.

Parameters

CacheTime	$entry
PageRecord	$page
int	$staleConstraint	One of USE_* constants.
string	$cacheTier

Returns: bool

Definition at line 568 of file ParserCache.php.

References CacheTime\getCacheRevisionId(), Page\PageRecord\getLatest(), and incrementStats().

Referenced by get(), and getMetadata().

◆ deleteOptionsKey()

ParserCache::deleteOptionsKey ( PageRecord $page )

Parameters

PageRecord $page

Since: 1.28

Definition at line 183 of file ParserCache.php.

References MediaWiki\DAO\WikiAwareEntity\assertWiki(), and makeMetadataKey().

◆ encodeAsJson()

ParserCache::encodeAsJson	(	CacheTime	$obj,
		string	$key
	)

private

Parameters

CacheTime	$obj
string	$key

Returns: string|null

Definition at line 624 of file ParserCache.php.

Referenced by save().

◆ get()

ParserCache::get	(	PageRecord	$page,
			$popts,
			$useOutdated = `false`
	)

Retrieve the ParserOutput from ParserCache.

false if not found or outdated.

Parameters

PageRecord	$page
ParserOptions	$popts
bool	$useOutdated	(default false)

Returns: ParserOutput|false

Definition at line 326 of file ParserCache.php.

References MediaWiki\DAO\WikiAwareEntity\assertWiki(), checkExpired(), checkOutdated(), Page\PageIdentity\exists(), getMetadata(), incrementStats(), Page\PageRecord\isRedirect(), makeParserOutputKey(), BagOStuff\READ_VERIFIED, restoreFromJson(), USE_CURRENT_ONLY, and USE_OUTDATED.

◆ getCacheStorage()

ParserCache::getCacheStorage ( )

Get the backend BagOStuff instance that powers the parser cache.

Since: 1.30

Access: internal

Returns: BagOStuff

Definition at line 527 of file ParserCache.php.

References $cache.

◆ getDirty()

ParserCache::getDirty	(	PageRecord	$page,
			$popts
	)

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

Parameters

PageRecord	$page
ParserOptions	$popts

Returns: ParserOutput|false

Definition at line 196 of file ParserCache.php.

References MediaWiki\DAO\WikiAwareEntity\assertWiki(), and true.

Referenced by RefreshLinksJob\getParserOutputFromCache().

◆ getMetadata()

ParserCache::getMetadata	(	PageRecord	$page,
		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

PageRecord	$page
int	$staleConstraint	one of the self::USE_ constants

Returns: ParserCacheMetadata|null

Since: 1.36

Definition at line 226 of file ParserCache.php.

References MediaWiki\DAO\WikiAwareEntity\assertWiki(), checkExpired(), checkOutdated(), incrementStats(), makeMetadataKey(), BagOStuff\READ_VERIFIED, and restoreFromJson().

Referenced by get().

◆ incrementStats()

ParserCache::incrementStats	(	PageRecord	$page,
			$metricSuffix
	)

private

Parameters

PageRecord	$page
string	$metricSuffix

Definition at line 206 of file ParserCache.php.

Referenced by checkExpired(), checkOutdated(), get(), getMetadata(), and save().

◆ makeMetadataKey()

ParserCache::makeMetadataKey ( PageRecord $page )

private

Parameters

PageRecord $page

Returns: string

Definition at line 280 of file ParserCache.php.

References Page\ProperPageIdentity\getId().

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

◆ makeParserOutputKey()

ParserCache::makeParserOutputKey	(	PageRecord	$page,
		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

PageRecord	$page
ParserOptions	$options
array \| null	$usedOptions	Defaults to all cache varying options.

Returns: string

Access: internal

Since: 1.36

Definition at line 300 of file ParserCache.php.

References $title, ParserOptions\allCacheVaryingOptions(), Page\ProperPageIdentity\getId(), and ParserOptions\optionsHash().

Referenced by get(), and save().

◆ restoreFromJson()

ParserCache::restoreFromJson	(	string	$jsonData,
		string	$key,
		string	$expectedClass
	)

private

Parameters

string	$jsonData
string	$key
string	$expectedClass

Returns: CacheTime|ParserOutput|null

Definition at line 604 of file ParserCache.php.

Referenced by get(), and getMetadata().

◆ save()

ParserCache::save	(	ParserOutput	$parserOutput,
		PageRecord	$page,
			$popts,
			$cacheTime = `null`,
			$revId = `null`
	)

Parameters

ParserOutput	$parserOutput
PageRecord	$page
ParserOptions	$popts
string \| null	$cacheTime	TS_MW timestamp when the cache was generated
int \| null	$revId	Revision ID that was parsed

Definition at line 409 of file ParserCache.php.

References $title, ParserOutput\addCacheMessage(), MediaWiki\DAO\WikiAwareEntity\assertWiki(), encodeAsJson(), CacheTime\getCacheExpiry(), Page\PageRecord\getLatest(), CacheTime\getUsedOptions(), ParserOutput\hasText(), incrementStats(), makeMetadataKey(), makeParserOutputKey(), CacheTime\recordOptions(), CacheTime\setCacheRevisionId(), CacheTime\setCacheTime(), wfTimestampNow(), and BagOStuff\WRITE_ALLOW_SEGMENTS.

◆ setJsonSupport()

ParserCache::setJsonSupport	(	bool	$readJson,
		bool	$writeJson
	)

Note: setter for temporary feature flags, for use in testing.

Access: internal

Parameters

bool	$readJson
bool	$writeJson

Definition at line 593 of file ParserCache.php.

References $readJson, and $writeJson.

Member Data Documentation

◆ $cache

BagOStuff ParserCache::$cache

private

Definition at line 89 of file ParserCache.php.

Referenced by __construct(), and getCacheStorage().

◆ $cacheEpoch

string ParserCache::$cacheEpoch

private

Anything cached prior to this is invalidated.

Definition at line 96 of file ParserCache.php.

Referenced by __construct().

◆ $hookRunner

HookRunner ParserCache::$hookRunner

private

Definition at line 99 of file ParserCache.php.

◆ $jsonCodec

JsonCodec ParserCache::$jsonCodec

private

Definition at line 102 of file ParserCache.php.

Referenced by __construct().

◆ $logger

LoggerInterface ParserCache::$logger

private

Definition at line 108 of file ParserCache.php.

Referenced by __construct().

◆ $metadataProcCache

BagOStuff ParserCache::$metadataProcCache

private

small in-process cache to store metadata.

It's needed multiple times during the request, for example to build a PoolWorkArticleView key, and then to fetch the actual ParserCache entry.

Definition at line 122 of file ParserCache.php.

◆ $name

string ParserCache::$name

private

The name of this ParserCache.

Used as a root of the cache key.

Definition at line 86 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 134 of file ParserCache.php.

Referenced by setJsonSupport().

◆ $stats

IBufferingStatsdDataFactory ParserCache::$stats

private

Definition at line 105 of file ParserCache.php.

Referenced by __construct().

◆ $titleFactory

TitleFactory ParserCache::$titleFactory

private

Definition at line 111 of file ParserCache.php.

Referenced by __construct().

◆ $wikiPageFactory

WikiPageFactory ParserCache::$wikiPageFactory

private

Definition at line 114 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 128 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 83 of file ParserCache.php.

◆ 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 71 of file ParserCache.php.

Referenced by get().

◆ USE_EXPIRED

const ParserCache::USE_EXPIRED = 1

Use expired data if current data is unavailable.

Definition at line 74 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 77 of file ParserCache.php.

Referenced by get().

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

includes/parser/ParserCache.php

Public Member Functions

Public Attributes

Private Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ __construct()

Member Function Documentation

◆ checkExpired()

◆ checkOutdated()

◆ deleteOptionsKey()

◆ encodeAsJson()

◆ get()

◆ getCacheStorage()

◆ getDirty()

◆ getMetadata()

◆ incrementStats()

◆ makeMetadataKey()

◆ makeParserOutputKey()

◆ restoreFromJson()

◆ save()

◆ setJsonSupport()

Member Data Documentation

◆ $cache

◆ $cacheEpoch

◆ $hookRunner

◆ $jsonCodec

◆ $logger

◆ $metadataProcCache

◆ $name

◆ $readJson

◆ $stats

◆ $titleFactory

◆ $wikiPageFactory

◆ $writeJson

◆ USE_ANYTHING

◆ USE_CURRENT_ONLY

◆ USE_EXPIRED

◆ USE_OUTDATED