From: Aaron Schulz <aschulz@wikimedia.org>
Date: Sun, 6 Jan 2019 21:55:14 +0000 (-0800)
Subject: objectcache: add more "touchedCallback" comments to WANObjectCache
X-Git-Tag: 1.34.0-rc.0~3127^2
X-Git-Url: https://git.heureux-cyclage.org/?p=lhc%2Fweb%2Fwiklou.git;a=commitdiff_plain;h=fe3959e5916d49e00ad13d2f53c5c58600f6060d

objectcache: add more "touchedCallback" comments to WANObjectCache

Change-Id: I55775216154aba0042f7c4cf1cb07336aa4a222e
---

diff --git a/includes/libs/objectcache/WANObjectCache.php b/includes/libs/objectcache/WANObjectCache.php
index 4bbebd6cc5..6e8d266e14 100644
--- a/includes/libs/objectcache/WANObjectCache.php
+++ b/includes/libs/objectcache/WANObjectCache.php
@@ -941,6 +941,36 @@ class WANObjectCache implements IExpiringStore, LoggerAwareInterface {
 	 *     );
 	 * @endcode
 	 *
+	 * Example usage (key that is expensive with too many DB dependencies for "check keys"):
+	 * @code
+	 *     $catToys = $cache->getWithSetCallback(
+	 *         // Key to store the cached value under
+	 *         $cache->makeKey( 'cat-toys', $catId ),
+	 *         // Time-to-live (seconds)
+	 *         $cache::TTL_HOUR,
+	 *         // Function that derives the new key value
+	 *         function ( $oldValue, &$ttl, array &$setOpts ) {
+	 *             // Determine new value from the DB
+	 *             $dbr = wfGetDB( DB_REPLICA );
+	 *             // Account for any snapshot/replica DB lag
+	 *             $setOpts += Database::getCacheSetOptions( $dbr );
+	 *
+	 *             return CatToys::newFromResults( $dbr->select( ... ) );
+	 *         },
+	 *         [
+	 *              // Get the highest timestamp of any of the cat's toys
+	 *             'touchedCallback' => function ( $value ) use ( $catId ) {
+	 *                 $dbr = wfGetDB( DB_REPLICA );
+	 *                 $ts = $dbr->selectField( 'cat_toys', 'MAX(ct_touched)', ... );
+	 *
+	 *                 return wfTimestampOrNull( TS_UNIX, $ts );
+	 *             },
+	 *             // Avoid DB queries for repeated access
+	 *             'pcTTL' => $cache::TTL_PROC_SHORT
+	 *         ]
+	 *     );
+	 * @endcode
+	 *
 	 * Example usage (hot key holding most recent 100 events):
 	 * @code
 	 *     $lastCatActions = $cache->getWithSetCallback(
@@ -1082,8 +1112,8 @@ class WANObjectCache implements IExpiringStore, LoggerAwareInterface {
 	 *      expired for this specified time. This is useful if adaptiveTTL() is used on the old
 	 *      value's as-of time when it is verified as still being correct.
 	 *      Default: WANObjectCache::STALE_TTL_NONE
-	 *   - touchedCallback: A callback that takes the current value and returns a timestamp that
-	 *      indicates the last time a dynamic dependency changed. Null can be returned if there
+	 *   - touchedCallback: A callback that takes the current value and returns a UNIX timestamp
+	 *      indicating the last time a dynamic dependency changed. Null can be returned if there
 	 *      are no relevant dependency changes to check. This can be used to check against things
 	 *      like last-modified times of files or DB timestamp fields. This should generally not be
 	 *      used for small and easily queried values in a DB if the callback itself ends up doing