Daniel Kinzler has uploaded a new change for review.
https://gerrit.wikimedia.org/r/233994
Change subject: Add comments clarifying how calling getters on ParserOutput
affects the parser cache.
......................................................................
Add comments clarifying how calling getters on ParserOutput affects the parser
cache.
Change-Id: Ie6a4a8989df218f88cfc7c1cf1d4b68cf871abbb
---
M includes/parser/ParserOptions.php
M includes/parser/ParserOutput.php
2 files changed, 20 insertions(+), 9 deletions(-)
git pull ssh://gerrit.wikimedia.org:29418/mediawiki/core
refs/changes/94/233994/1
diff --git a/includes/parser/ParserOptions.php
b/includes/parser/ParserOptions.php
index ed0d74a..87424e0 100644
--- a/includes/parser/ParserOptions.php
+++ b/includes/parser/ParserOptions.php
@@ -372,18 +372,17 @@
}
/**
- * Get the user language used by the parser for this page and record the
- * userlang parser option, which splits parser cache.
+ * Get the user language used by the parser for this page and split the
parser cache.
*
- * You shouldn't use this. Really. $parser->getFunctionLang() is all
you need.
+ * @warning: Calling this causes the parser cache to be fragmented by
user language!
+ * To avoid cache fragmentation, output should not depend on the user
language.
+ * Use Parser::getFunctionLang() or Parser::getTargetLanguage() instead!
*
- * To avoid side-effects where the page will be rendered based on the
language
- * of the user who last saved, this function will trigger a cache
fragmentation.
- * For that reason, usage of this method is discouraged unless it is
desired to
- * split caches based on user language, such as for multilingual
content.
+ * @note This function will trigger a cache fragmentation by recording
the
+ * 'userlang' option, see optionUsed(). This is done to avoid cache
pollution
+ * when the page is rendered based on the language of the user.
*
- * When saving, this will return the default language instead of the
user's.
- *
+ * @note When saving, this will return the default language instead of
the user's.
* {{int: }} uses this which used to produce inconsistent link tables
(bug 14404).
*
* @return Language
@@ -396,6 +395,12 @@
/**
* Same as getUserLangObj() but returns a string instead.
+ *
+ * @warning: Calling this causes the parser cache to be fragmented by
user language!
+ * To avoid cache fragmentation, output should not depend on the user
language.
+ * Use Parser::getFunctionLang() or Parser::getTargetLanguage() instead!
+ *
+ * @see getUserLangObj()
*
* @return string Language code
* @since 1.17
@@ -702,6 +707,10 @@
/**
* Called when an option is accessed.
+ * Calls the watcher that was set using registerWatcher().
+ * Typically, the watcher callback is ParserOutput::registerOption().
+ * The information registered that way will be used by
ParserCache::save().
+ *
* @param string $optionName Name of the option
*/
public function optionUsed( $optionName ) {
diff --git a/includes/parser/ParserOutput.php b/includes/parser/ParserOutput.php
index 15321c2..2eb1dc9 100644
--- a/includes/parser/ParserOutput.php
+++ b/includes/parser/ParserOutput.php
@@ -686,6 +686,8 @@
/**
* Tags a parser option for use in the cache key for this parser output.
* Registered as a watcher at ParserOptions::registerWatcher() by
Parser::clearState().
+ * The information gathered here is available via getUsedOptions(),
+ * and is used by ParserCache::save().
*
* @see ParserCache::getKey
* @see ParserCache::save
--
To view, visit https://gerrit.wikimedia.org/r/233994
To unsubscribe, visit https://gerrit.wikimedia.org/r/settings
Gerrit-MessageType: newchange
Gerrit-Change-Id: Ie6a4a8989df218f88cfc7c1cf1d4b68cf871abbb
Gerrit-PatchSet: 1
Gerrit-Project: mediawiki/core
Gerrit-Branch: master
Gerrit-Owner: Daniel Kinzler <[email protected]>
_______________________________________________
MediaWiki-commits mailing list
[email protected]
https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
