Scrapbook

StampedeProtector
in package

Scrapbook

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 to 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.

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 (or the everything for the given collection).
get() : mixed|bool: Retrieves an item from the cache.
getCollection() : KeyValueStore: Returns an isolated subset (collection) in which to store or fetch data from.
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.

__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

bool

cas()

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

bool

decrement()

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

bool

deleteMulti()

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 (or the everything for the given collection).


    public
                    flush() : bool

Return values

bool

get()

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

getCollection()

Returns an isolated subset (collection) in which to store or fetch data from.


    public
                    getCollection(mixed $name) : KeyValueStore

Parameters

$name : mixed

Return values

KeyValueStore —

A new KeyValueStore instance representing only a subset of data on this server

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

bool

set()

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

bool

setMulti()

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

Return values

bool

StampedeProtector in package Scrapbook implements KeyValueStore

Tags

Table of Contents

Interfaces

Methods

Methods

__construct()

Parameters

add()

Parameters

Return values

cas()

Parameters

Return values

decrement()

Parameters

Return values

delete()

Parameters

Return values

deleteMulti()

Parameters

Return values

flush()

Return values

get()

Parameters

Return values

getCollection()

Parameters

Return values

getMulti()

Parameters

Return values

increment()

Parameters

Return values

replace()

Parameters

Return values

set()

Parameters

Return values

setMulti()

Parameters

Return values

touch()

Parameters

Return values

StampedeProtector
in package

Scrapbook

implements KeyValueStore