const TTL_LAGGED = 30;
/** Idiom for delete() for "no hold-off" */
const HOLDOFF_NONE = 0;
+ /** Idiom for getWithSetCallback() for "no minimum required as-of timestamp" */
+ const MIN_TIMESTAMP_NONE = 0.0;
/** Tiny negative float to use when CTL comes up >= 0 due to clock skew */
const TINY_NEGATIVE = -0.000001;
* @param integer $ttl Seconds to live. Special values are:
* - WANObjectCache::TTL_INDEFINITE: Cache forever
* @param array $opts Options map:
- * - lag : Seconds of replica DB lag. Typically, this is either the replica DB lag
- * before the data was read or, if applicable, the replica DB lag before
- * the snapshot-isolated transaction the data was read from started.
- * Default: 0 seconds
- * - since : UNIX timestamp of the data in $value. Typically, this is either
- * the current time the data was read or (if applicable) the time when
- * the snapshot-isolated transaction the data was read from started.
- * Default: 0 seconds
+ * - lag : Seconds of replica DB lag. Typically, this is either the replica DB lag
+ * before the data was read or, if applicable, the replica DB lag before
+ * the snapshot-isolated transaction the data was read from started.
+ * Use false to indicate that replication is not running.
+ * Default: 0 seconds
+ * - since : UNIX timestamp of the data in $value. Typically, this is either
+ * the current time the data was read or (if applicable) the time when
+ * the snapshot-isolated transaction the data was read from started.
+ * Default: 0 seconds
* - pending : Whether this data is possibly from an uncommitted write transaction.
- * Generally, other threads should not see values from the future and
- * they certainly should not see ones that ended up getting rolled back.
- * Default: false
+ * Generally, other threads should not see values from the future and
+ * they certainly should not see ones that ended up getting rolled back.
+ * Default: false
* - lockTSE : if excessive replication/snapshot lag is detected, then store the value
- * with this TTL and flag it as stale. This is only useful if the reads for
- * this key use getWithSetCallback() with "lockTSE" set.
- * Default: WANObjectCache::TSE_NONE
+ * with this TTL and flag it as stale. This is only useful if the reads for
+ * this key use getWithSetCallback() with "lockTSE" set.
+ * Default: WANObjectCache::TSE_NONE
+ * - staleTTL : Seconds to keep the key around if it is stale. The get()/getMulti()
+ * methods return such stale values with a $curTTL of 0, and getWithSetCallback()
+ * will call the regeneration callback in such cases, passing in the old value
+ * and its as-of time to the callback. This is useful if adaptiveTTL() is used
+ * on the old value's as-of time when it is verified as still being correct.
+ * Default: 0.
+ * @note Options added in 1.28: staleTTL
* @return bool Success
*/
final public function set( $key, $value, $ttl = 0, array $opts = [] ) {
$lockTSE = isset( $opts['lockTSE'] ) ? $opts['lockTSE'] : self::TSE_NONE;
$age = isset( $opts['since'] ) ? max( 0, $now - $opts['since'] ) : 0;
$lag = isset( $opts['lag'] ) ? $opts['lag'] : 0;
+ $staleTTL = isset( $opts['staleTTL'] ) ? $opts['staleTTL'] : 0;
// Do not cache potentially uncommitted data as it might get rolled back
if ( !empty( $opts['pending'] ) ) {
: $wrapped;
};
- return $this->cache->merge( self::VALUE_KEY_PREFIX . $key, $func, $ttl, 1 );
+ return $this->cache->merge( self::VALUE_KEY_PREFIX . $key, $func, $ttl + $staleTTL, 1 );
}
/**
* - $oldValue : current cache value or false if not present
* - &$ttl : a reference to the TTL which can be altered
* - &$setOpts : a reference to options for set() which can be altered
+ * - $oldAsOf : generation UNIX timestamp of $oldValue or null if not present (since 1.28)
*
* It is strongly recommended to set the 'lag' and 'since' fields to avoid race conditions
* that can cause stale values to get stuck at keys. Usually, callbacks ignore the current
* versions are stored alongside older versions concurrently. Avoid storing class objects
* however, as this reduces compatibility (due to serialization).
* Default: null.
+ * - minAsOf: Reject values if they were generated before this UNIX timestamp.
+ * This is useful if the source of a key is suspected of having possibly changed
+ * recently, and the caller wants any such changes to be reflected.
+ * Default: WANObjectCache::MIN_TIMESTAMP_NONE.
* - hotTTR: Expected time-till-refresh for keys that average ~1 hit/second.
* This should be greater than "ageNew". Keys with higher hit rates will regenerate
* more often. This is useful when a popular key is changed but the cache purge was
* - ageNew: Consider popularity refreshes only once a key reaches this age in seconds.
* Default: WANObjectCache::AGE_NEW.
* @return mixed Value found or written to the key
+ * @note Options added in 1.28: version, busyValue, hotTTR, ageNew, pcGroup, minAsOf
* @note Callable type hints are not used to avoid class-autoloading
*/
final public function getWithSetCallback( $key, $ttl, $callback, array $opts = [] ) {
}
if ( $value === false ) {
- unset( $opts['minTime'] ); // not a public feature
-
// Fetch the value over the network
if ( isset( $opts['version'] ) ) {
$version = $opts['version'];
$cur = $this->doGetWithSetCallback(
$key,
$ttl,
- function ( $oldValue, &$ttl, &$setOpts ) use ( $callback, $version ) {
+ function ( $oldValue, &$ttl, &$setOpts, $oldAsOf )
+ use ( $callback, $version ) {
if ( is_array( $oldValue )
&& array_key_exists( self::VFLD_DATA, $oldValue )
) {
}
return [
- self::VFLD_DATA => $callback( $oldData, $ttl, $setOpts ),
+ self::VFLD_DATA => $callback( $oldData, $ttl, $setOpts, $oldAsOf ),
self::VFLD_VERSION => $version
];
},
$ttl,
$callback,
// Regenerate value if not newer than $key
- [ 'version' => null, 'minTime' => $asOf ] + $opts
+ [ 'version' => null, 'minAsOf' => $asOf ] + $opts
);
}
} else {
* @param string $key
* @param integer $ttl
* @param callback $callback
- * @param array $opts Options map for getWithSetCallback() which also includes:
- * - minTime: Treat values older than this UNIX timestamp as not existing. Default: null.
+ * @param array $opts Options map for getWithSetCallback()
* @param float &$asOf Cache generation timestamp of returned value [returned]
* @return mixed
* @note Callable type hints are not used to avoid class-autoloading
$busyValue = isset( $opts['busyValue'] ) ? $opts['busyValue'] : null;
$popWindow = isset( $opts['hotTTR'] ) ? $opts['hotTTR'] : self::HOT_TTR;
$ageNew = isset( $opts['ageNew'] ) ? $opts['ageNew'] : self::AGE_NEW;
- $minTime = isset( $opts['minTime'] ) ? $opts['minTime'] : 0.0;
+ $minTime = isset( $opts['minAsOf'] ) ? $opts['minAsOf'] : self::MIN_TIMESTAMP_NONE;
$versioned = isset( $opts['version'] );
// Get the current key value
// Generate the new value from the callback...
$setOpts = [];
- $value = call_user_func_array( $callback, [ $cValue, &$ttl, &$setOpts ] );
- $asOf = microtime( true );
+ $value = call_user_func_array( $callback, [ $cValue, &$ttl, &$setOpts, $asOf ] );
// When delete() is called, writes are write-holed by the tombstone,
// so use a special INTERIM key to pass the new value around threads.
if ( ( $isTombstone && $lockTSE > 0 ) && $value !== false && $ttl >= 0 ) {
$tempTTL = max( 1, (int)$lockTSE ); // set() expects seconds
- $wrapped = $this->wrap( $value, $tempTTL, $asOf );
+ $newAsOf = microtime( true );
+ $wrapped = $this->wrap( $value, $tempTTL, $newAsOf );
// Avoid using set() to avoid pointless mcrouter broadcasting
$this->cache->merge(
self::INTERIM_KEY_PREFIX . $key,
dépôts / lhc / web / wiklou.git / blobdiff