StampedeProtector
in package
implements
KeyValueStore
Cache is usually used to reduce performing a complex operation. In case of a cache miss, that operation is executed & the result is stored.
A cache stampede happens when there are a lot of requests for data that is not currently in cache. Examples could be:
- cache expires for something that is often under very heavy load
- sudden unexpected high load on something that is likely yo not be in cache In those cases, this huge amount of requests for data that is not at that time in cache, causes that expensive operation to be executed a lot of times, all at once.
This class is designed to counteract that: if a value can't be found in cache we'll write something else to cache for a short period of time, to indicate that another process has already requested this same key (and is probably already performing that complex operation that will result in the key being filled)
All of the follow-up requests (that find that the "stampede indicator" has already been set) will just wait (usleep): instead of crippling the servers by all having to execute the same operation, these processes will just idle to give the first process the chance to fill in the cache. Periodically, these processes will poll the cache to see if the value has already been stored in the meantime.
The stampede protection will only be temporary, for $sla milliseconds. We need to limit it because the first process (tasked with filling the cache after executing the expensive operation) may fail/crash/... If the expensive operation fails to conclude in < $sla milliseconds. This class guarantees that the stampede will hold off for $sla amount of time but after that, all follow-up requests will go through without cached values and cause a stampede after all, if the initial process fails to complete within that time.
Tags
Table of Contents
Interfaces
- KeyValueStore
- Interface for key-value storage engines.
Methods
- __construct() : mixed
- add() : bool
- Adds an item under new key.
- cas() : bool
- Replaces an item in 1 atomic operation, to ensure it didn't change since it was originally read, when the CAS token was issued.
- decrement() : int|bool
- Decrements a counter value, or sets an initial value if it does not yet exist.
- delete() : bool
- Deletes an item from the cache.
- deleteMulti() : array<string|int, bool>
- Deletes multiple items at once (reduced network traffic compared to individual operations).
- flush() : bool
- Clears the entire cache.
- get() : mixed|bool
- Retrieves an item from the cache.
- getMulti() : array<string|int, mixed>
- Retrieves multiple items at once.
- increment() : int|bool
- Increments a counter value, or sets an initial value if it does not yet exist.
- replace() : bool
- Replaces an item.
- set() : bool
- Stores a value, regardless of whether or not the key already exists (in which case it will overwrite the existing value for that key).
- setMulti() : array<string|int, bool>
- Store multiple values at once.
- touch() : bool
- Updates an item's expiration time without altering the stored value.
Methods
__construct()
public
__construct(KeyValueStore $cache[, int $sla = 1000 ]) : mixed
Parameters
- $cache : KeyValueStore
-
The real cache we'll buffer for.
- $sla : int = 1000
-
Stampede protection time, in milliseconds
add()
Adds an item under new key.
public
add(mixed $key, mixed $value[, mixed $expire = 0 ]) : bool
Parameters
- $key : mixed
- $value : mixed
- $expire : mixed = 0
-
Time when item falls out of the cache: 0 = permanent (doesn't expires); under 2592000 (30 days) = relative time, in seconds from now; over 2592000 = absolute time, unix timestamp
Return values
boolcas()
Replaces an item in 1 atomic operation, to ensure it didn't change since it was originally read, when the CAS token was issued.
public
cas(mixed $token, mixed $key, mixed $value[, mixed $expire = 0 ]) : bool
Parameters
- $token : mixed
-
Token received from get() or getMulti()
- $key : mixed
- $value : mixed
- $expire : mixed = 0
-
Time when item falls out of the cache: 0 = permanent (doesn't expires); under 2592000 (30 days) = relative time, in seconds from now; over 2592000 = absolute time, unix timestamp
Return values
booldecrement()
Decrements a counter value, or sets an initial value if it does not yet exist.
public
decrement(mixed $key[, mixed $offset = 1 ][, mixed $initial = 0 ][, mixed $expire = 0 ]) : int|bool
Parameters
- $key : mixed
- $offset : mixed = 1
-
Value to decrement with
- $initial : mixed = 0
-
Initial value (if item doesn't yet exist)
- $expire : mixed = 0
-
Time when item falls out of the cache: 0 = permanent (doesn't expires); under 2592000 (30 days) = relative time, in seconds from now; over 2592000 = absolute time, unix timestamp
Return values
int|bool —New value or false on failure
delete()
Deletes an item from the cache.
public
delete(mixed $key) : bool
Parameters
- $key : mixed
Return values
booldeleteMulti()
Deletes multiple items at once (reduced network traffic compared to individual operations).
public
deleteMulti(array<string|int, mixed> $keys) : array<string|int, bool>
Parameters
- $keys : array<string|int, mixed>
Return values
array<string|int, bool>flush()
Clears the entire cache.
public
flush() : bool
Return values
boolget()
Retrieves an item from the cache.
public
get(mixed $key[, mixed &$token = null ]) : mixed|bool
Parameters
- $key : mixed
- $token : mixed = null
-
Will be filled with the CAS token
Return values
mixed|bool —Value, or false on failure
getMulti()
Retrieves multiple items at once.
public
getMulti(array<string|int, mixed> $keys[, array<string|int, mixed> &$tokens = null ]) : array<string|int, mixed>
Parameters
- $keys : array<string|int, mixed>
- $tokens : array<string|int, mixed> = null
-
Will be filled with the CAS tokens, in [key => token] format
Return values
array<string|int, mixed> —[key => value]
increment()
Increments a counter value, or sets an initial value if it does not yet exist.
public
increment(mixed $key[, mixed $offset = 1 ][, mixed $initial = 0 ][, mixed $expire = 0 ]) : int|bool
Parameters
- $key : mixed
- $offset : mixed = 1
-
Value to increment with
- $initial : mixed = 0
-
Initial value (if item doesn't yet exist)
- $expire : mixed = 0
-
Time when item falls out of the cache: 0 = permanent (doesn't expires); under 2592000 (30 days) = relative time, in seconds from now; over 2592000 = absolute time, unix timestamp
Return values
int|bool —New value or false on failure
replace()
Replaces an item.
public
replace(mixed $key, mixed $value[, mixed $expire = 0 ]) : bool
Parameters
- $key : mixed
- $value : mixed
- $expire : mixed = 0
-
Time when item falls out of the cache: 0 = permanent (doesn't expires); under 2592000 (30 days) = relative time, in seconds from now; over 2592000 = absolute time, unix timestamp
Return values
boolset()
Stores a value, regardless of whether or not the key already exists (in which case it will overwrite the existing value for that key).
public
set(mixed $key, mixed $value[, mixed $expire = 0 ]) : bool
Parameters
- $key : mixed
- $value : mixed
- $expire : mixed = 0
-
Time when item falls out of the cache: 0 = permanent (doesn't expires); under 2592000 (30 days) = relative time, in seconds from now; over 2592000 = absolute time, unix timestamp
Return values
boolsetMulti()
Store multiple values at once.
public
setMulti(array<string|int, mixed> $items[, mixed $expire = 0 ]) : array<string|int, bool>
Parameters
- $items : array<string|int, mixed>
-
[key => value]
- $expire : mixed = 0
-
Time when item falls out of the cache: 0 = permanent (doesn't expires); under 2592000 (30 days) = relative time, in seconds from now; over 2592000 = absolute time, unix timestamp
Return values
array<string|int, bool>touch()
Updates an item's expiration time without altering the stored value.
public
touch(mixed $key, mixed $expire) : bool
Parameters
- $key : mixed
- $expire : mixed
-
Time when item falls out of the cache: 0 = permanent (doesn't expires); under 2592000 (30 days) = relative time, in seconds from now; over 2592000 = absolute time, unix timestamp