BlueSpice MediaWiki master
 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, callable $callback, $exptime=0, $attempts=10, $flags=0)
 
 changeTTL ($key, $expiry=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 ()
 
 addBusyCallback (callable $workCallback)
 
 modifySimpleRelayEvent (array $event)
 
 makeKeyInternal ($keyspace, $args)
 
 makeGlobalKey ($class, $component=null)
 
 makeKey ($class, $component=null)
 
 getQoS ($flag)
 

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_SECOND = 1
 
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_PROC_SHORT = 3
 
const TTL_PROC_LONG = 30
 
const TTL_INDEFINITE = 0
 
const ATTR_EMULATION = 1
 
const QOS_EMULATION_SQL = 1
 
const ATTR_SYNCWRITES = 2
 
const QOS_SYNCWRITES_NONE = 1
 
const QOS_SYNCWRITES_BE = 2
 
const QOS_SYNCWRITES_QC = 3
 
const QOS_SYNCWRITES_SS = 4
 
const QOS_UNKNOWN = INF
 

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)
 
 mergeFlagMaps (array $bags)
 

Protected Attributes

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

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).
  • syncTimeout: How long to wait with WRITE_SYNC in seconds.
    Parameters
    array$params

Member Function Documentation

BagOStuff::add (   $key,
  $value,
  $exptime = 0 
)
Parameters
string$key
mixed$value
int$exptime
Returns
bool Success
BagOStuff::addBusyCallback ( callable  $workCallback)

Let a callback be run to avoid wasting time on special blocking calls

The callbacks may or may not be called ever, in any particular order. They are likely to be invoked when something WRITE_SYNC is used used. They should follow a caching pattern as shown below, so that any code using the word will get it's result no matter what happens.

$result = null;
$workCallback = function () use ( &$result ) {
if ( !$result ) {
$result = ....
}
return $result;
}
Parameters
callable$workCallback
Since
1.28
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::changeTTL (   $key,
  $expiry = 0 
)

Reset the TTL on a key if it exists

Parameters
string$key
int$expiry
Returns
bool Success Returns false if there is no key
Since
1.28
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
int$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
int$flagsBitfield of BagOStuff::READ_* constants [optional]
int$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
int$flagsBitfield; supports READ_LATEST [optional]
Returns
array
BagOStuff::getQoS (   $flag)
Parameters
int$flagATTR_* class constant
Returns
int QOS_* class constant
Since
1.28
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
int$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
int$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 (   $class,
  $component = null 
)

Make a global cache key.

Since
1.27
Parameters
string$classKey class
string$component[optional] Key component (starting with a key collection name)
Returns
string Colon-delimited list of $keyspace followed by escaped components of $args
BagOStuff::makeKey (   $class,
  $component = null 
)

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

Since
1.27
Parameters
string$classKey class
string$component[optional] Key component (starting with a key collection name)
Returns
string Colon-delimited list of $keyspace followed by escaped components of $args
BagOStuff::makeKeyInternal (   $keyspace,
  $args 
)

Construct a cache key.

Since
1.27
Parameters
string$keyspace
array$args
Returns
string Colon-delimited list of $keyspace followed by escaped components of $args
BagOStuff::merge (   $key,
callable  $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, TTL). The TTL parameter is reference set to $exptime. It can be overriden in the callback.

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::mergeFlagMaps ( array  $bags)
protected

Merge the flag maps of one or more BagOStuff objects into a "lowest common denominator" map

Parameters
BagOStuff[]$bags
Returns
int[] Resulting flag map (class ATTR_* constant => class QOS_* constant)
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: