Scrapbook

Transaction
in package
implements KeyValueStore

This is a helper class for BufferedStore & TransactionalStore, which buffer real cache requests in memory.

This class accepts 2 caches: a KeyValueStore object (the real cache) and a Buffer instance (to read data from as long as it hasn't been committed)

Every write action will first store the data in the Buffer instance, and then store the update to be performed in $deferred. Once commit() is called, all those $deferred updates are executed against the real cache. All deferred writes that fail to apply will cause that cache key to be deleted, to ensure cache consistency. Until commit() is called, all data is read from the temporary Buffer instance.

Tags
author

Matthias Mullie [email protected]

copyright

Copyright (c) 2014, Matthias Mullie. All rights reserved.

license

MIT License

Table of Contents

Interfaces

KeyValueStore
Interface for key-value storage engines.

Methods

__construct()  : mixed
__destruct()  : mixed
add()  : bool
Adds an item under new key.
cas()  : bool
Since our CAS is deferred, the CAS token we got from our original get() will likely not be valid by the time we want to store it to the real cache. Imagine this scenario: * a value is fetched from (real) cache * an new value key is CAS'ed (into temp cache - real CAS is deferred) * this key's value is fetched again (this time from temp cache) * and a new value is CAS'ed again (into temp cache...).
commit()  : bool
Commits all deferred updates to real cache.
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.
rollback()  : bool
Roll back all scheduled changes.
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

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()

Since our CAS is deferred, the CAS token we got from our original get() will likely not be valid by the time we want to store it to the real cache. Imagine this scenario: * a value is fetched from (real) cache * an new value key is CAS'ed (into temp cache - real CAS is deferred) * this key's value is fetched again (this time from temp cache) * and a new value is CAS'ed again (into temp cache...).

public cas(mixed $token, mixed $key, mixed $value[, mixed $expire = 0 ]) : bool

In this scenario, when we finally want to replay the write actions onto the real cache, the first 3 actions would likely work fine. The last (second CAS) however would not, since it never got a real updated $token from the real cache.

To work around this problem, all get() calls will return a unique CAS token and store the value-at-that-time associated with that token. All we have to do when we want to write the data to real cache is, right before was CAS for real, get the value & (real) cas token from storage & compare that value to the one we had stored. If that checks out, we can safely resume the CAS with the real token we just received.

Should a deferred CAS fail, however, we'll delete the key in cache since it's no longer reliable.

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

commit()

Commits all deferred updates to real cache.

public commit() : bool

If the any write fails, all subsequent writes will be aborted & all keys that had already been written to will be deleted.

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.

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

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

rollback()

Roll back all scheduled changes.

public rollback() : bool
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 

        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results