Improved getWithSetCallback() docs to have more use cases

Change-Id: I428617c159009f22fa78129c16a8964ac2e830b9

diff --git a/includes/libs/objectcache/WANObjectCache.php b/includes/libs/objectcache/WANObjectCache.php
index e8d1e5e..e5bc665 100644 (file)
--- a/includes/libs/objectcache/WANObjectCache.php
+++ b/includes/libs/objectcache/WANObjectCache.php
@@ -510,40 +510,108 @@ class WANObjectCache {
         * single thread updates it as needed. Also consider tweaking
         * the 'lowTTL' parameter.
         *
         * single thread updates it as needed. Also consider tweaking
         * the 'lowTTL' parameter.
         *

-        * Example usage:
+        * Example usage (typical key):

         * @code
         * @code

-        *     $key = wfMemcKey( 'cat-recent-actions', $catId );
-        *     // Function that derives the new key value given the old value
-        *     $callback = function( $cValue, &$ttl, array &$setOpts ) {
-        *         $dbr = wfGetDB( DB_SLAVE );
-        *         // Fetch the row from the DB
-        *         $row = $dbr->selectRow( ... );
-        *         // Give the age of the transaction snapshot the data came from
-        *         $setOpts = array( 'since' => $dbr->trxTimestamp() );
-        *         return $row;
-        *     };
-        *     // Get the key value from cache or from source on cache miss;
-        *     // try to only let one datacenter thread manage doing cache updates
-        *     $opts = array( 'lockTSE' => 5, 'lowTTL' => 10 );
-        *     $value = $cache->getWithSetCallback( $key, $callback, 60, array(), $opts );
+        *     $catInfo = $cache->getWithSetCallback(
+        *         // Key to store the cached value under
+        *         wfMemcKey( 'cat-attributes', $catId ),
+        *         // Function that derives the new key value
+        *         function( $oldValue, &$ttl, array &$setOpts ) {
+        *             // Fetch row from the DB
+        *             $dbr = wfGetDB( DB_SLAVE );
+        *             $row = $dbr->selectRow( ... );
+        *
+        *             // Set age of the transaction snapshot the data came from
+        *             $setOpts = array( 'since' => $dbr->trxTimestamp() );
+        *
+        *             return $row;
+        *        },
+        *        // Time-to-live (seconds)
+        *        60
+        *     );

         * @endcode
         *
         * @endcode
         *

-        * Example usage:
+        * Example usage (key that is expensive and hot):
+        * @code
+        *     $catConfig = $cache->getWithSetCallback(
+        *         // Key to store the cached value under
+        *         wfMemcKey( 'site-cat-config' ),
+        *         // Function that derives the new key value
+        *         function( $oldValue, &$ttl, array &$setOpts ) {
+        *             // Fetch row from the DB
+        *             $dbr = wfGetDB( DB_SLAVE );
+        *             $config = CatConfig::newFromRow( $dbr->selectRow( ... ) );
+        *
+        *             // Set age of the transaction snapshot the data came from
+        *             $setOpts = array( 'since' => $dbr->trxTimestamp() );
+        *
+        *             return $config;
+        *        },
+        *        // Time-to-live (seconds)
+        *        86400,
+        *        // Calling touchCheckKey() on this key invalidates the cache
+        *        wfMemcKey( 'site-cat-config' ),
+        *        // Try to only let one datacenter thread manage cache updates at a time
+        *        array( 'lockTSE' => 30 )
+        *     );
+        * @endcode
+        *
+        * Example usage (key with dynamic dependencies):

         * @code
         * @code

-        *     $key = wfMemcKey( 'cat-state', $catId );
-        *     // The "check" keys that represent things the value depends on;
-        *     // Calling touchCheckKey() on them invalidates "cat-state"
-        *     $checkKeys = array(
-        *         wfMemcKey( 'water-bowls', $houseId ),
-        *         wfMemcKey( 'food-bowls', $houseId ),
-        *         wfMemcKey( 'people-present', $houseId )
+        *     $catState = $cache->getWithSetCallback(
+        *         // Key to store the cached value under
+        *         wfMemcKey( 'cat-state', $cat->getId() ),
+        *         // Function that derives the new key value
+        *         function( $oldValue, &$ttl, array &$setOpts ) {
+        *             // Determine new value from the DB
+        *             $dbr = wfGetDB( DB_SLAVE );
+        *             $state = CatState::newFromResults( $dbr->select( ... ) );
+        *
+        *             // Set age of the transaction snapshot the data came from
+        *             $setOpts = array( 'since' => $dbr->trxTimestamp() );
+        *
+        *             return $state;
+        *        },
+        *        // Time-to-live (seconds)
+        *        900,
+        *        // The "check" keys that represent things the value depends on;
+        *        // Calling touchCheckKey() on any of them invalidates the cache
+        *        array(
+        *             wfMemcKey( 'sustenance-bowls', $cat->getRoomId() ),
+        *             wfMemcKey( 'people-present', $cat->getHouseId() ),
+        *             wfMemcKey( 'cat-laws', $cat->getCityId() ),
+        *         )

         *     );
         *     );

-        *     // Function that derives the new key value
-        *     $callback = function() { ... };
-        *     // Get the key value from cache or from source on cache miss;
-        *     // try to only let one datacenter thread manage doing cache updates
-        *     $opts = array( 'lockTSE' => 5, 'lowTTL' => 10 );
-        *     $value = $cache->getWithSetCallback( $key, $callback, 60, $checkKeys, $opts );
+        * @endcode
+        *
+        * Example usage (hot key holding most recent 100 events):
+        * @code
+        *     $lastCatActions = $cache->getWithSetCallback(
+        *         // Key to store the cached value under
+        *         wfMemcKey( 'cat-last-actions', 100 ),
+        *         // Function that derives the new key value
+        *         function( $oldValue, &$ttl, array &$setOpts ) {
+        *             $dbr = wfGetDB( DB_SLAVE );
+        *             // Start off with the last cached list
+        *             $list = $oldValue ? $oldValue : array();
+        *             $last = end( $list );
+        *             // Fetch any rows newer than $last from the DB (in order)
+        *             $rows = iterator_to_array( $dbr->select( ... ) );
+        *             // Merge them and get the new "last 100" rows
+        *             $list = array_slice( array_merge( $list, $new ), -100 );
+        *
+        *             // Set age of the transaction snapshot the data came from
+        *             $setOpts = array( 'since' => $dbr->trxTimestamp() );
+        *
+        *             return $list;
+        *        },
+        *        // Time-to-live (seconds)
+        *        10
+        *        // No "check" keys
+        *        array(),
+        *        // Try to only let one datacenter thread manage cache updates at a time
+        *        array( 'lockTSE' => 30 )
+        *     ) );

         * @endcode
         *
         * @see WANObjectCache::get()
         * @endcode
         *
         * @see WANObjectCache::get()