BlueSpice MediaWiki REL1_27
 All Classes Namespaces Files Functions Variables Groups Pages
BagOStuff Class Reference
Inheritance diagram for BagOStuff:
Collaboration diagram for BagOStuff:

Public Member Functions

 __construct (array $params=[])
 
 setLogger (LoggerInterface $logger)
 
 setDebug ($bool)
 
 getWithSetCallback ($key, $ttl, $callback, $flags=0)
 
 get ($key, $flags=0, $oldFlags=null)
 
 set ($key, $value, $exptime=0, $flags=0)
 
 delete ($key)
 
 merge ($key, $callback, $exptime=0, $attempts=10, $flags=0)
 
 lock ($key, $timeout=6, $expiry=6, $rclass= '')
 
 unlock ($key)
 
 getScopedLock ($key, $timeout=6, $expiry=30, $rclass= '')
 
 deleteObjectsExpiringBefore ($date, $progressCallback=false)
 
 getMulti (array $keys, $flags=0)
 
 setMulti (array $data, $exptime=0)
 
 add ($key, $value, $exptime=0)
 
 incr ($key, $value=1)
 
 decr ($key, $value=1)
 
 incrWithInit ($key, $ttl, $value=1, $init=1)
 
 getLastError ()
 
 clearLastError ()
 
 modifySimpleRelayEvent (array $event)
 
 makeKeyInternal ($keyspace, $args)
 
 makeGlobalKey ()
 
 makeKey ()
 

Public Attributes

const ERR_NONE = 0
 
const ERR_NO_RESPONSE = 1
 
const ERR_UNREACHABLE = 2
 
const ERR_UNEXPECTED = 3
 
const READ_LATEST = 1
 
const READ_VERIFIED = 2
 
const WRITE_SYNC = 1
 
const WRITE_CACHE_ONLY = 2
 
- Public Attributes inherited from IExpiringStore
const TTL_MINUTE = 60
 
const TTL_HOUR = 3600
 
const TTL_DAY = 86400
 
const TTL_WEEK = 604800
 
const TTL_MONTH = 2592000
 
const TTL_YEAR = 31536000
 
const TTL_INDEFINITE = 0
 

Protected Member Functions

 doGet ($key, $flags=0)
 
 getWithToken ($key, &$casToken, $flags=0)
 
 mergeViaCas ($key, $callback, $exptime=0, $attempts=10)
 
 cas ($casToken, $key, $value, $exptime=0)
 
 mergeViaLock ($key, $callback, $exptime=0, $attempts=10, $flags=0)
 
 setLastError ($err)
 
 debug ($text)
 
 convertExpiry ($exptime)
 
 convertToRelative ($exptime)
 
 isInteger ($value)
 

Protected Attributes

 $locks = []
 
 $lastError = self::ERR_NONE
 
 $keyspace = 'local'
 
 $logger
 
 $asyncHandler
 

Detailed Description

interface is intended to be more or less compatible with the PHP memcached client.

backends for local hash array and SQL table included:

$bag = new HashBagOStuff();
$bag = new SqlBagOStuff(); # connect to db first

Constructor & Destructor Documentation

BagOStuff::__construct ( array  $params = [])

$params include:

  • logger: Psr instance
  • keyspace: Default keyspace for $this->makeKey()
  • asyncHandler: Callable to use for scheduling tasks after the web request ends. In CLI mode, it should run the task immediately.
  • reportDupes: Whether to emit warning log messages for all keys that were requested more than once (requires an asyncHandler).
    Parameters
    array$params

Member Function Documentation

BagOStuff::add (   $key,
  $value,
  $exptime = 0 
)
Parameters
string$key
mixed$value
int$exptime
Returns
bool Success
BagOStuff::cas (   $casToken,
  $key,
  $value,
  $exptime = 0 
)
protected

Check and set an item

Parameters
mixed$casToken
string$key
mixed$value
int$exptimeEither an interval in seconds or a unix timestamp for expiry
Returns
bool Success
Exceptions
Exception
BagOStuff::clearLastError ( )

Clear the "last error" registry

Since
1.23
BagOStuff::convertExpiry (   $exptime)
protected

Convert an optionally relative time to an absolute time

Parameters
int$exptime
Returns
int
BagOStuff::convertToRelative (   $exptime)
protected

Convert an optionally absolute expiry time to a relative time. If an absolute time is specified which is in the past, use a short expiry time.

Parameters
int$exptime
Returns
int
BagOStuff::debug (   $text)
protected
Parameters
string$text
BagOStuff::decr (   $key,
  $value = 1 
)

Decrease stored value of $key by $value while preserving its TTL

Parameters
string$key
int$value
Returns
int|bool New value or false on failure
BagOStuff::delete (   $key)
abstract

Delete an item

Parameters
string$key
Returns
bool True if the item was deleted or not found, false on failure
BagOStuff::deleteObjectsExpiringBefore (   $date,
  $progressCallback = false 
)

Delete all objects expiring before a certain date.

Parameters
string$dateThe reference date in MW format
callable | bool$progressCallbackOptional, a function which will be called regularly during long-running operations with the percentage progress as the first parameter.
Returns
bool Success, false if unimplemented
BagOStuff::doGet (   $key,
  $flags = 0 
)
abstractprotected
Parameters
string$key
integer$flagsBitfield of BagOStuff::READ_* constants [optional]
Returns
mixed Returns false on failure and if the item does not exist
BagOStuff::get (   $key,
  $flags = 0,
  $oldFlags = null 
)

Get an item with the given key

If the key includes a determistic input hash (e.g. the key can only have the correct value) or complete staleness checks are handled by the caller (e.g. nothing relies on the TTL), then the READ_VERIFIED flag should be set. This lets tiered backends know they can safely upgrade a cached value to higher tiers using standard TTLs.

Parameters
string$key
integer$flagsBitfield of BagOStuff::READ_* constants [optional]
integer$oldFlags[unused]
Returns
mixed Returns false on failure and if the item does not exist
BagOStuff::getLastError ( )

Get the "last error" registered; clearLastError() should be called manually

Returns
int ERR_* constant for the "last error" registry
Since
1.23
BagOStuff::getMulti ( array  $keys,
  $flags = 0 
)

Get an associative array containing the item for each of the keys that have items.

Parameters
array$keysList of strings
integer$flagsBitfield; supports READ_LATEST [optional]
Returns
array
BagOStuff::getScopedLock (   $key,
  $timeout = 6,
  $expiry = 30,
  $rclass = '' 
)
final

Get a lightweight exclusive self-unlocking lock

Note that the same lock cannot be acquired twice.

This is useful for task de-duplication or to avoid obtrusive (though non-corrupting) DB errors like INSERT key conflicts or deadlocks when using LOCK IN SHARE MODE.

Parameters
string$key
int$timeoutLock wait timeout; 0 for non-blocking [optional]
int$expiryLock expiry [optional]; 1 day maximum
string$rclassAllow reentry if set and the current lock used this value
Returns
ScopedCallback|null Returns null on failure
Since
1.26
BagOStuff::getWithSetCallback (   $key,
  $ttl,
  $callback,
  $flags = 0 
)
final

Get an item with the given key, regenerating and setting it if not found

If the callback returns false, then nothing is stored.

Parameters
string$key
int$ttlTime-to-live (seconds)
callable$callbackCallback that derives the new value
integer$flagsBitfield of BagOStuff::READ_* constants [optional]
Returns
mixed The cached value if found or the result of $callback otherwise
Since
1.27
BagOStuff::getWithToken (   $key,
$casToken,
  $flags = 0 
)
protected
Note
: This method is only needed if merge() uses mergeViaCas()
Parameters
string$key
mixed$casToken
integer$flagsBitfield of BagOStuff::READ_* constants [optional]
Returns
mixed Returns false on failure and if the item does not exist
Exceptions
Exception
BagOStuff::incr (   $key,
  $value = 1 
)

Increase stored value of $key by $value while preserving its TTL

Parameters
string$keyKey to increase
int$valueValue to add to $key (Default 1)
Returns
int|bool New value or false on failure
BagOStuff::incrWithInit (   $key,
  $ttl,
  $value = 1,
  $init = 1 
)

Increase stored value of $key by $value while preserving its TTL

This will create the key with value $init and TTL $ttl instead if not present

Parameters
string$key
int$ttl
int$value
int$init
Returns
int|bool New value or false on failure
Since
1.24
BagOStuff::isInteger (   $value)
protected

Check if a value is an integer

Parameters
mixed$value
Returns
bool
BagOStuff::lock (   $key,
  $timeout = 6,
  $expiry = 6,
  $rclass = '' 
)

Acquire an advisory lock on a key string

Note that if reentry is enabled, duplicate calls ignore $expiry

Parameters
string$key
int$timeoutLock wait timeout; 0 for non-blocking [optional]
int$expiryLock expiry [optional]; 1 day maximum
string$rclassAllow reentry if set and the current lock used this value
Returns
bool Success
BagOStuff::makeGlobalKey ( )

Make a global cache key.

Since
1.27
Parameters
string... Key component (variadic)
Returns
string
BagOStuff::makeKey ( )

Make a cache key, scoped to this instance's keyspace.

Since
1.27
Parameters
string... Key component (variadic)
Returns
string
BagOStuff::makeKeyInternal (   $keyspace,
  $args 
)

Construct a cache key.

Since
1.27
Parameters
string$keyspace
array$args
Returns
string
BagOStuff::merge (   $key,
  $callback,
  $exptime = 0,
  $attempts = 10,
  $flags = 0 
)

Merge changes into the existing cache value (possibly creating a new one). The callback function returns the new value given the current value (which will be false if not present), and takes the arguments: (this BagOStuff, cache key, current value).

Parameters
string$key
callable$callbackCallback method to be executed
int$exptimeEither an interval in seconds or a unix timestamp for expiry
int$attemptsThe amount of times to attempt a merge in case of failure
int$flagsBitfield of BagOStuff::WRITE_* constants
Returns
bool Success
Exceptions
InvalidArgumentException
BagOStuff::mergeViaCas (   $key,
  $callback,
  $exptime = 0,
  $attempts = 10 
)
protected
See Also
BagOStuff::merge()
Parameters
string$key
callable$callbackCallback method to be executed
int$exptimeEither an interval in seconds or a unix timestamp for expiry
int$attemptsThe amount of times to attempt a merge in case of failure
Returns
bool Success
BagOStuff::mergeViaLock (   $key,
  $callback,
  $exptime = 0,
  $attempts = 10,
  $flags = 0 
)
protected
See Also
BagOStuff::merge()
Parameters
string$key
callable$callbackCallback method to be executed
int$exptimeEither an interval in seconds or a unix timestamp for expiry
int$attemptsThe amount of times to attempt a merge in case of failure
int$flagsBitfield of BagOStuff::WRITE_* constants
Returns
bool Success
BagOStuff::modifySimpleRelayEvent ( array  $event)

Modify a cache update operation array for EventRelayer::notify()

This is used for relayed writes, e.g. for broadcasting a change to multiple data-centers. If the array contains a 'val' field then the command involves setting a key to that value. Note that for simplicity, 'val' is always a simple scalar value. This method is used to possibly serialize the value and add any cache-specific key/values needed for the relayer daemon (e.g. memcached flags).

Parameters
array$event
Returns
array
Since
1.26
BagOStuff::set (   $key,
  $value,
  $exptime = 0,
  $flags = 0 
)
abstract

Set an item

Parameters
string$key
mixed$value
int$exptimeEither an interval in seconds or a unix timestamp for expiry
int$flagsBitfield of BagOStuff::WRITE_* constants
Returns
bool Success
BagOStuff::setDebug (   $bool)
Parameters
bool$bool
BagOStuff::setLastError (   $err)
protected

Set the "last error" registry

Parameters
int$errERR_* constant
Since
1.23
BagOStuff::setLogger ( LoggerInterface  $logger)
Parameters
LoggerInterface$logger
Returns
null

Implements Psr\Log\LoggerAwareInterface.

BagOStuff::setMulti ( array  $data,
  $exptime = 0 
)

Batch insertion

Parameters
array$data$key => $value assoc array
int$exptimeEither an interval in seconds or a unix timestamp for expiry
Returns
bool Success
Since
1.24
BagOStuff::unlock (   $key)

Release an advisory lock on a key string

Parameters
string$key
Returns
bool Success

Member Data Documentation

const BagOStuff::ERR_NONE = 0

Possible values for getLastError()

const BagOStuff::READ_LATEST = 1

Bitfield constants for get()/getMulti()

const BagOStuff::WRITE_SYNC = 1

Bitfield constants for set()/merge()


The documentation for this class was generated from the following file: