MediaWiki REL1_40
MemcachedClient Class Reference

memcached client class implemented using (p)fsockopen() More...

Inherits Wikimedia\LightweightObjectStore\StorageAwareness.

Collaboration diagram for MemcachedClient:

Public Member Functions

 __construct ( $args)
 Memcache initializer.
 
 _close_sock ( $sock)
 Close the specified socket.
 
 _connect_sock (&$sock, $host)
 Connects $sock to $host, timing out after $timeout.
 
 _dead_host ( $host)
 
 _dead_sock ( $sock)
 Marks a host as dead until 30-40 seconds in the future.
 
 _debugprint ( $text)
 
 _error_log ( $text)
 
 _fgets ( $sock)
 Read a line from a stream.
 
 _flush_read_buffer ( $f)
 Flush the read buffer of a stream.
 
 _fread ( $sock, $len)
 Read the specified number of bytes from a stream.
 
 _fwrite ( $sock, $buf)
 Write to a stream.
 
 _handle_error ( $sock, $msg)
 Handle an I/O error.
 
 _hashfunc ( $key)
 Creates a hash integer based on the $key.
 
 _incrdecr ( $cmd, $key, $amt=1)
 Perform increment/decrement on $key.
 
 _load_items ( $sock, &$ret, &$casToken=null)
 Load items into $ret from $sock.
 
 _set ( $cmd, $key, $val, $exp, $casToken=null)
 Performs the requested storage operation to the memcache server.
 
 add ( $key, $val, $exp=0)
 Adds a key/value to the memcache server if one isn't already set with that key.
 
 cas ( $casToken, $key, $value, $exp=0)
 Sets a key to a given value in the memcache if the current value still corresponds to a known, given value.
 
 decr ( $key, $amt=1)
 Decrease a value stored on the memcache server.
 
 delete ( $key, $time=0)
 Deletes a key from the server, optionally after $time.
 
 disconnect_all ()
 Disconnects all connected sockets.
 
 enable_compress ( $enable)
 Enable / Disable compression.
 
 forget_dead_hosts ()
 Forget about all of the dead hosts.
 
 get ( $key, &$casToken=null)
 Retrieves the value associated with the key from the memcache server.
 
 get_multi ( $keys)
 Get multiple keys from the server(s)
 
 get_sock ( $key)
 get_sock
 
 incr ( $key, $amt=1)
 Increments $key (optionally) by $amt.
 
 replace ( $key, $value, $exp=0)
 Overwrites an existing value for key; only works if key is already set.
 
 run_command ( $sock, $cmd)
 Passes through $cmd to the memcache server connected by $sock; returns output as an array (null array if no output)
 
 serialize ( $value)
 
 set ( $key, $value, $exp=0)
 Unconditionally sets a key to a given value in the memcache.
 
 set_compress_threshold ( $thresh)
 Set the compression threshold.
 
 set_debug ( $dbg)
 Set the debug flag.
 
 set_servers ( $list)
 Set the server list to distribute key gets and puts between.
 
 set_timeout ( $seconds, $microseconds)
 Sets the timeout for new connections.
 
 sock_to_host ( $host)
 Returns the socket for the host.
 
 touch ( $key, $time=0)
 Changes the TTL on a key from the server to $time.
 
 unserialize ( $value)
 

Public Attributes

int $_active
 
int $_bucketcount
 Total # of bit buckets we have.
 
array $_buckets
 Our bit buckets.
 
array $_cache_sock
 Cached Sockets that are connected.
 
bool $_compress_enable
 Do we want to use compression?
 
int $_compress_threshold
 At how many bytes should we compress?
 
 $_connect_attempts
 Number of connection attempts for each server.
 
 $_connect_timeout
 Connect timeout in seconds.
 
bool $_debug
 Current debug status; 0 - none to 9 - profiling.
 
bool $_have_zlib
 Is compression available?
 
array $_host_dead
 Dead hosts, assoc array, 'host'=>'unixtime when ok to check again'.
 
int $_last_cmd_status = self::ERR_NONE
 StorageAwareness:ERR_* constant of the last cache command.
 
bool $_persistent
 Are we using persistent links?
 
array $_servers
 Array containing ip:port or array(ip:port, weight)
 
string $_single_sock
 If only using one server; contains ip:port to connect to.
 
int $_timeout_microseconds
 Stream timeout in microseconds.
 
int $_timeout_seconds
 Stream timeout in seconds.
 
array $stats
 Command statistics.
 
const COMPRESSED = 2
 Flag: indicates data is compressed.
 
const COMPRESSION_SAVINGS = 0.20
 Minimum savings to store data compressed.
 
const INTVAL = 4
 Flag: indicates data is an integer.
 
const SERIALIZED = 1
 Flag: indicates data is serialized.
 
- Public Attributes inherited from Wikimedia\LightweightObjectStore\StorageAwareness
const ATTR_DURABILITY = 2
 Durability of writes; see QOS_DURABILITY_* (higher means stronger)
 
const ATTR_EMULATION = 1
 Emulation/fallback mode; see QOS_EMULATION_*; higher is better.
 
const ERR_NO_RESPONSE = 1
 Storage medium failed to yield a complete response to an operation.
 
const ERR_NONE = 0
 No storage medium error.
 
const ERR_UNEXPECTED = 3
 Storage medium operation failed due to usage limitations or an I/O error.
 
const ERR_UNREACHABLE = 2
 Storage medium could not be reached to establish a connection.
 
const QOS_DURABILITY_DISK = 4
 Data is saved to disk and writes do not usually block on fsync()
 
const QOS_DURABILITY_NONE = 1
 Data is never saved to begin with (blackhole store)
 
const QOS_DURABILITY_RDBMS = 5
 Data is saved to disk and writes usually block on fsync(), like a standard RDBMS.
 
const QOS_DURABILITY_SCRIPT = 2
 Data is lost at the end of the current web request or CLI script.
 
const QOS_DURABILITY_SERVICE = 3
 Data is lost once the service storing the data restarts.
 
const QOS_EMULATION_SQL = 1
 Fallback disk-based SQL store.
 
const QOS_UNKNOWN = INF
 Generic "unknown" value; useful for comparisons (always "good enough")
 

Detailed Description

memcached client class implemented using (p)fsockopen()

Author
Ryan T. Dean rtdea.nosp@m.n@cy.nosp@m.theri.nosp@m.anag.nosp@m.e.net

Definition at line 82 of file MemcachedClient.php.

Constructor & Destructor Documentation

◆ __construct()

MemcachedClient::__construct ( $args)

Memcache initializer.

Parameters
array$argsAssociative array of settings

Definition at line 266 of file MemcachedClient.php.

References set_servers().

Member Function Documentation

◆ _close_sock()

MemcachedClient::_close_sock ( $sock)

Close the specified socket.

Parameters
string$sockSocket to close
Access: private

Definition at line 806 of file MemcachedClient.php.

◆ _connect_sock()

MemcachedClient::_connect_sock ( & $sock,
$host )

Connects $sock to $host, timing out after $timeout.

Parameters
int$sockSocket to connect
string$hostHost:IP to connect to
Returns
bool
Access: private

Definition at line 824 of file MemcachedClient.php.

References $_connect_attempts, $_connect_timeout, _dead_host(), _error_log(), and _flush_read_buffer().

Referenced by sock_to_host().

◆ _dead_host()

MemcachedClient::_dead_host ( $host)
Parameters
string$host

Definition at line 882 of file MemcachedClient.php.

Referenced by _connect_sock(), and _dead_sock().

◆ _dead_sock()

MemcachedClient::_dead_sock ( $sock)

Marks a host as dead until 30-40 seconds in the future.

Parameters
string$sockSocket to mark as dead
Access: private

Definition at line 874 of file MemcachedClient.php.

References _dead_host().

Referenced by _handle_error().

◆ _debugprint()

MemcachedClient::_debugprint ( $text)
Parameters
string$text

Definition at line 1245 of file MemcachedClient.php.

Referenced by _incrdecr(), _set(), delete(), get(), get_multi(), and touch().

◆ _error_log()

MemcachedClient::_error_log ( $text)
Parameters
string$text

Definition at line 1252 of file MemcachedClient.php.

Referenced by _connect_sock(), and _handle_error().

◆ _fgets()

MemcachedClient::_fgets ( $sock)

Read a line from a stream.

If there is an error, mark the socket dead. The \r\n line ending is stripped from the response.

Parameters
Resource$sockThe socket
Returns
string|bool The string on success, false on failure

Definition at line 1342 of file MemcachedClient.php.

References _handle_error().

Referenced by _incrdecr(), _load_items(), _set(), delete(), run_command(), and touch().

◆ _flush_read_buffer()

MemcachedClient::_flush_read_buffer ( $f)

Flush the read buffer of a stream.

Parameters
Resource$f

Definition at line 1371 of file MemcachedClient.php.

Referenced by _connect_sock().

◆ _fread()

MemcachedClient::_fread ( $sock,
$len )

Read the specified number of bytes from a stream.

If there is an error, mark the socket dead.

Parameters
Resource$sockThe socket
int$lenThe number of bytes to read
Returns
string|bool The string on success, false on failure.

Definition at line 1311 of file MemcachedClient.php.

References _handle_error().

Referenced by _load_items().

◆ _fwrite()

MemcachedClient::_fwrite ( $sock,
$buf )

Write to a stream.

If there is an error, mark the socket dead.

Parameters
Resource$sockThe socket
string$bufThe string to write
Returns
bool True on success, false on failure

Definition at line 1263 of file MemcachedClient.php.

References _handle_error().

Referenced by _incrdecr(), _set(), delete(), get(), get_multi(), run_command(), and touch().

◆ _handle_error()

MemcachedClient::_handle_error ( $sock,
$msg )

Handle an I/O error.

Mark the socket dead and log an error.

Parameters
Resource$sock
string$msg

Definition at line 1290 of file MemcachedClient.php.

References _dead_sock(), and _error_log().

Referenced by _fgets(), _fread(), _fwrite(), and _load_items().

◆ _hashfunc()

MemcachedClient::_hashfunc ( $key)

Creates a hash integer based on the $key.

Parameters
string$keyKey to hash
Returns
int Hash value
Access: private

Definition at line 954 of file MemcachedClient.php.

Referenced by get_sock().

◆ _incrdecr()

MemcachedClient::_incrdecr ( $cmd,
$key,
$amt = 1 )

Perform increment/decrement on $key.

Parameters
string$cmdCommand to perform
string | array$keyKey to perform it on
int$amtAmount to adjust
Returns
int New value of $key
Access: private

Definition at line 974 of file MemcachedClient.php.

References _debugprint(), _fgets(), _fwrite(), Wikimedia\LightweightObjectStore\StorageAwareness\ERR_NO_RESPONSE, Wikimedia\LightweightObjectStore\StorageAwareness\ERR_NONE, Wikimedia\LightweightObjectStore\StorageAwareness\ERR_UNEXPECTED, Wikimedia\LightweightObjectStore\StorageAwareness\ERR_UNREACHABLE, and get_sock().

Referenced by decr(), and incr().

◆ _load_items()

MemcachedClient::_load_items ( $sock,
& $ret,
& $casToken = null )

Load items into $ret from $sock.

Parameters
Resource$sockSocket to read from
array$retreturned values
float$casToken[optional]
Returns
bool True for success, false for failure
Access: private

Definition at line 1030 of file MemcachedClient.php.

References _fgets(), _fread(), _handle_error(), and unserialize().

Referenced by get(), and get_multi().

◆ _set()

MemcachedClient::_set ( $cmd,
$key,
$val,
$exp,
$casToken = null )

Performs the requested storage operation to the memcache server.

Parameters
string$cmdCommand to perform
string$keyKey to act on
mixed$valWhat we need to store
int$exp(optional) Expiration time. This can be a number of seconds to cache for (up to 30 days inclusive). Any timespans of 30 days + 1 second or longer must be the timestamp of the time at which the mapping should expire. It is safe to use timestamps in all cases, regardless of expiration eg: strtotime("+3 hour")
float$casToken[optional]
Returns
bool
Access: private

Definition at line 1118 of file MemcachedClient.php.

References _debugprint(), _fgets(), _fwrite(), COMPRESSED, Wikimedia\LightweightObjectStore\StorageAwareness\ERR_NO_RESPONSE, Wikimedia\LightweightObjectStore\StorageAwareness\ERR_NONE, Wikimedia\LightweightObjectStore\StorageAwareness\ERR_UNEXPECTED, Wikimedia\LightweightObjectStore\StorageAwareness\ERR_UNREACHABLE, get_sock(), INTVAL, serialize(), and SERIALIZED.

Referenced by add(), cas(), replace(), and set().

◆ add()

MemcachedClient::add ( $key,
$val,
$exp = 0 )

Adds a key/value to the memcache server if one isn't already set with that key.

Parameters
string$keyKey to set with data
mixed$valValue to store
int$exp(optional) Expiration time. This can be a number of seconds to cache for (up to 30 days inclusive). Any timespans of 30 days + 1 second or longer must be the timestamp of the time at which the mapping should expire. It is safe to use timestamps in all cases, regardless of expiration eg: strtotime("+3 hour")
Returns
bool

Definition at line 321 of file MemcachedClient.php.

References _set(), and Wikimedia\LightweightObjectStore\StorageAwareness\ERR_NONE.

◆ cas()

MemcachedClient::cas ( $casToken,
$key,
$value,
$exp = 0 )

Sets a key to a given value in the memcache if the current value still corresponds to a known, given value.

Returns true if set successfully.

Parameters
float$casTokenCurrent known value
string$keyKey to set value as
mixed$valueValue to set
int$exp(optional) Expiration time. This can be a number of seconds to cache for (up to 30 days inclusive). Any timespans of 30 days + 1 second or longer must be the timestamp of the time at which the mapping should expire. It is safe to use timestamps in all cases, regardless of expiration eg: strtotime("+3 hour")
Returns
bool True on success

Definition at line 733 of file MemcachedClient.php.

References _set().

◆ decr()

MemcachedClient::decr ( $key,
$amt = 1 )

Decrease a value stored on the memcache server.

Parameters
string$keyKey to decrease
int$amt(optional) amount to decrease
Returns
mixed False on failure, value on success

Definition at line 338 of file MemcachedClient.php.

References _incrdecr(), and Wikimedia\LightweightObjectStore\StorageAwareness\ERR_NONE.

◆ delete()

MemcachedClient::delete ( $key,
$time = 0 )

Deletes a key from the server, optionally after $time.

Parameters
string$keyKey to delete
int$time(optional) how long to wait before deleting
Returns
bool True on success, false on failure

Definition at line 355 of file MemcachedClient.php.

References $res, _debugprint(), _fgets(), _fwrite(), Wikimedia\LightweightObjectStore\StorageAwareness\ERR_NONE, Wikimedia\LightweightObjectStore\StorageAwareness\ERR_UNEXPECTED, and get_sock().

◆ disconnect_all()

MemcachedClient::disconnect_all ( )

Disconnects all connected sockets.

Definition at line 443 of file MemcachedClient.php.

◆ enable_compress()

MemcachedClient::enable_compress ( $enable)

Enable / Disable compression.

Parameters
bool$enableTrue to enable, false to disable

Definition at line 459 of file MemcachedClient.php.

◆ forget_dead_hosts()

MemcachedClient::forget_dead_hosts ( )

Forget about all of the dead hosts.

Definition at line 469 of file MemcachedClient.php.

◆ get()

MemcachedClient::get ( $key,
& $casToken = null )

◆ get_multi()

◆ get_sock()

MemcachedClient::get_sock ( $key)

get_sock

Parameters
string$keyKey to retrieve value for;
Returns
Resource|bool Resource on success, false on failure
Access: private

Definition at line 905 of file MemcachedClient.php.

References $_bucketcount, _hashfunc(), and sock_to_host().

Referenced by _incrdecr(), _set(), delete(), get(), get_multi(), and touch().

◆ incr()

MemcachedClient::incr ( $key,
$amt = 1 )

Increments $key (optionally) by $amt.

Parameters
string$keyKey to increment
int$amt(optional) amount to increment
Returns
int|null Null if the key does not exist yet (this does NOT create new mappings if the key does not exist). If the key does exist, this returns the new value for that key.

Definition at line 635 of file MemcachedClient.php.

References _incrdecr().

◆ replace()

MemcachedClient::replace ( $key,
$value,
$exp = 0 )

Overwrites an existing value for key; only works if key is already set.

Parameters
string$keyKey to set value as
mixed$valueValue to store
int$exp(optional) Expiration time. This can be a number of seconds to cache for (up to 30 days inclusive). Any timespans of 30 days + 1 second or longer must be the timestamp of the time at which the mapping should expire. It is safe to use timestamps in all cases, regardless of expiration eg: strtotime("+3 hour")
Returns
bool

Definition at line 655 of file MemcachedClient.php.

References _set().

◆ run_command()

MemcachedClient::run_command ( $sock,
$cmd )

Passes through $cmd to the memcache server connected by $sock; returns output as an array (null array if no output)

Parameters
Resource$sockSocket to send command on
string$cmdCommand to run
Returns
array Output array

Definition at line 671 of file MemcachedClient.php.

References $res, _fgets(), and _fwrite().

◆ serialize()

MemcachedClient::serialize ( $value)
Parameters
mixed$value
Returns
string|integer

Definition at line 293 of file MemcachedClient.php.

References serialize().

Referenced by _set(), get(), and serialize().

◆ set()

MemcachedClient::set ( $key,
$value,
$exp = 0 )

Unconditionally sets a key to a given value in the memcache.

Returns true if set successfully.

Parameters
string$keyKey to set value as
mixed$valueValue to set
int$exp(optional) Expiration time. This can be a number of seconds to cache for (up to 30 days inclusive). Any timespans of 30 days + 1 second or longer must be the timestamp of the time at which the mapping should expire. It is safe to use timestamps in all cases, regardless of expiration eg: strtotime("+3 hour")
Returns
bool True on success

Definition at line 711 of file MemcachedClient.php.

References _set().

◆ set_compress_threshold()

MemcachedClient::set_compress_threshold ( $thresh)

Set the compression threshold.

Parameters
int$threshThreshold to compress if larger than

Definition at line 745 of file MemcachedClient.php.

◆ set_debug()

MemcachedClient::set_debug ( $dbg)

Set the debug flag.

See also
__construct()
Parameters
bool$dbgTrue for debugging, false otherwise

Definition at line 758 of file MemcachedClient.php.

◆ set_servers()

MemcachedClient::set_servers ( $list)

Set the server list to distribute key gets and puts between.

See also
__construct()
Parameters
array$listArray of servers to connect to

Definition at line 771 of file MemcachedClient.php.

Referenced by __construct().

◆ set_timeout()

MemcachedClient::set_timeout ( $seconds,
$microseconds )

Sets the timeout for new connections.

Parameters
int$secondsNumber of seconds
int$microsecondsNumber of microseconds

Definition at line 789 of file MemcachedClient.php.

◆ sock_to_host()

MemcachedClient::sock_to_host ( $host)

Returns the socket for the host.

Parameters
string$hostHost:IP to get socket for
Returns
Resource|bool IO Stream or false
Access: private

Definition at line 1211 of file MemcachedClient.php.

References _connect_sock().

Referenced by get_sock().

◆ touch()

MemcachedClient::touch ( $key,
$time = 0 )

Changes the TTL on a key from the server to $time.

Parameters
string$key
int$timeTTL in seconds
Returns
bool True on success, false on failure

Definition at line 401 of file MemcachedClient.php.

References $res, _debugprint(), _fgets(), _fwrite(), Wikimedia\LightweightObjectStore\StorageAwareness\ERR_NONE, and get_sock().

◆ unserialize()

MemcachedClient::unserialize ( $value)
Parameters
string$value
Returns
mixed

Definition at line 301 of file MemcachedClient.php.

References unserialize().

Referenced by _load_items(), and unserialize().

Member Data Documentation

◆ $_active

int MemcachedClient::$_active

of total servers we have

Access: private

Definition at line 218 of file MemcachedClient.php.

◆ $_bucketcount

int MemcachedClient::$_bucketcount

Total # of bit buckets we have.

Access: private

Definition at line 210 of file MemcachedClient.php.

Referenced by get_sock().

◆ $_buckets

array MemcachedClient::$_buckets

Our bit buckets.

Access: private

Definition at line 202 of file MemcachedClient.php.

◆ $_cache_sock

array MemcachedClient::$_cache_sock

Cached Sockets that are connected.

Access: private

Definition at line 130 of file MemcachedClient.php.

◆ $_compress_enable

bool MemcachedClient::$_compress_enable

Do we want to use compression?

Access: private

Definition at line 162 of file MemcachedClient.php.

◆ $_compress_threshold

int MemcachedClient::$_compress_threshold

At how many bytes should we compress?

Access: private

Definition at line 170 of file MemcachedClient.php.

◆ $_connect_attempts

MemcachedClient::$_connect_attempts

Number of connection attempts for each server.

Definition at line 244 of file MemcachedClient.php.

Referenced by _connect_sock().

◆ $_connect_timeout

MemcachedClient::$_connect_timeout

Connect timeout in seconds.

Definition at line 239 of file MemcachedClient.php.

Referenced by _connect_sock().

◆ $_debug

bool MemcachedClient::$_debug

Current debug status; 0 - none to 9 - profiling.

Access: private

Definition at line 138 of file MemcachedClient.php.

◆ $_have_zlib

bool MemcachedClient::$_have_zlib

Is compression available?

Access: private

Definition at line 154 of file MemcachedClient.php.

◆ $_host_dead

array MemcachedClient::$_host_dead

Dead hosts, assoc array, 'host'=>'unixtime when ok to check again'.

Access: private

Definition at line 146 of file MemcachedClient.php.

◆ $_last_cmd_status

int MemcachedClient::$_last_cmd_status = self::ERR_NONE

StorageAwareness:ERR_* constant of the last cache command.

Definition at line 247 of file MemcachedClient.php.

◆ $_persistent

bool MemcachedClient::$_persistent

Are we using persistent links?

Access: private

Definition at line 178 of file MemcachedClient.php.

◆ $_servers

array MemcachedClient::$_servers

Array containing ip:port or array(ip:port, weight)

Access: private

Definition at line 194 of file MemcachedClient.php.

◆ $_single_sock

string MemcachedClient::$_single_sock

If only using one server; contains ip:port to connect to.

Access: private

Definition at line 186 of file MemcachedClient.php.

◆ $_timeout_microseconds

int MemcachedClient::$_timeout_microseconds

Stream timeout in microseconds.

Access: private

Definition at line 234 of file MemcachedClient.php.

◆ $_timeout_seconds

int MemcachedClient::$_timeout_seconds

Stream timeout in seconds.

Applies for example to fread()

Access: private

Definition at line 226 of file MemcachedClient.php.

◆ $stats

array MemcachedClient::$stats

Command statistics.

Access: public

Definition at line 119 of file MemcachedClient.php.

◆ COMPRESSED

const MemcachedClient::COMPRESSED = 2

Flag: indicates data is compressed.

Definition at line 97 of file MemcachedClient.php.

Referenced by _set().

◆ COMPRESSION_SAVINGS

const MemcachedClient::COMPRESSION_SAVINGS = 0.20

Minimum savings to store data compressed.

Definition at line 109 of file MemcachedClient.php.

◆ INTVAL

const MemcachedClient::INTVAL = 4

Flag: indicates data is an integer.

Definition at line 102 of file MemcachedClient.php.

Referenced by _set().

◆ SERIALIZED

const MemcachedClient::SERIALIZED = 1

Flag: indicates data is serialized.

Definition at line 92 of file MemcachedClient.php.

Referenced by _set().


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