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

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_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 81 of file MemcachedClient.php.

Constructor & Destructor Documentation

◆ __construct()

MemcachedClient::__construct ( $args )

Memcache initializer.

Parameters

array $args Associative array of settings

Definition at line 265 of file MemcachedClient.php.

References set_servers().

Member Function Documentation

◆ _close_sock()

MemcachedClient::_close_sock ( $sock )

Close the specified socket.

Parameters

string $sock Socket to close

Access: private

Definition at line 805 of file MemcachedClient.php.

◆ _connect_sock()

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

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

Parameters

int	$sock	Socket to connect
string	$host	Host:IP to connect to

Returns: bool

Access: private

Definition at line 823 of file MemcachedClient.php.

References _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 881 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 $sock Socket to mark as dead

Access: private

Definition at line 873 of file MemcachedClient.php.

References _dead_host().

Referenced by _handle_error().

◆ _debugprint()

MemcachedClient::_debugprint ( $text )

Parameters

string $text

Definition at line 1244 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 1251 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 $sock The socket

Returns: string|bool The string on success, false on failure

Definition at line 1341 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 1370 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	$sock	The socket
int	$len	The number of bytes to read

Returns: string|bool The string on success, false on failure.

Definition at line 1310 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	$sock	The socket
string	$buf	The string to write

Returns: bool True on success, false on failure

Definition at line 1262 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 1289 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 $key Key to hash

Returns: int Hash value

Access: private

Definition at line 953 of file MemcachedClient.php.

Referenced by get_sock().

◆ _incrdecr()

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

Perform increment/decrement on $key.

Parameters

string	$cmd	Command to perform
string \| array	$key	Key to perform it on
int	$amt	Amount to adjust

Returns: int New value of $key

Access: private

Definition at line 973 of file MemcachedClient.php.

References _debugprint(), _fgets(), _fwrite(), 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	$sock	Socket to read from
array	$ret	returned values
float	$casToken	[optional]

Returns: bool True for success, false for failure

Access: private

Definition at line 1029 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	$cmd	Command to perform
string	$key	Key to act on
mixed	$val	What 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 1117 of file MemcachedClient.php.

References _debugprint(), _fgets(), _fwrite(), get_sock(), and serialize().

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	$key	Key to set with data
mixed	$val	Value 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 320 of file MemcachedClient.php.

References _set().

◆ 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	$casToken	Current known value
string	$key	Key to set value as
mixed	$value	Value 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 732 of file MemcachedClient.php.

References _set().

◆ decr()

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

Decrease a value stored on the memcache server.

Parameters

string	$key	Key to decrease
int	$amt	(optional) amount to decrease

Returns: mixed False on failure, value on success

Definition at line 337 of file MemcachedClient.php.

References _incrdecr().

◆ delete()

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

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

Parameters

string	$key	Key to delete
int	$time	(optional) how long to wait before deleting

Returns: bool True on success, false on failure

Definition at line 354 of file MemcachedClient.php.

References _debugprint(), _fgets(), _fwrite(), and get_sock().

◆ disconnect_all()

MemcachedClient::disconnect_all ( )

Disconnects all connected sockets.

Definition at line 442 of file MemcachedClient.php.

◆ enable_compress()

MemcachedClient::enable_compress ( $enable )

Enable / Disable compression.

Parameters

bool $enable True to enable, false to disable

Definition at line 458 of file MemcachedClient.php.

◆ forget_dead_hosts()

MemcachedClient::forget_dead_hosts ( )

Forget about all of the dead hosts.

Definition at line 468 of file MemcachedClient.php.

◆ get()

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

Retrieves the value associated with the key from the memcache server.

Parameters

array \| string	$key	key to retrieve
float	$casToken	[optional]

Returns: mixed

Definition at line 483 of file MemcachedClient.php.

References _debugprint(), _fwrite(), _load_items(), get_sock(), and serialize().

◆ get_multi()

MemcachedClient::get_multi ( $keys )

Get multiple keys from the server(s)

Parameters

array $keys Keys to retrieve

Returns: array

Definition at line 556 of file MemcachedClient.php.

References _debugprint(), _fwrite(), _load_items(), and get_sock().

◆ get_sock()

MemcachedClient::get_sock ( $key )

get_sock

Parameters

string $key Key to retrieve value for;

Returns: Resource|bool Resource on success, false on failure

Access: private

Definition at line 904 of file MemcachedClient.php.

References _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	$key	Key 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 634 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	$key	Key to set value as
mixed	$value	Value 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 654 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	$sock	Socket to send command on
string	$cmd	Command to run

Returns: array Output array

Definition at line 670 of file MemcachedClient.php.

References _fgets(), and _fwrite().

◆ serialize()

MemcachedClient::serialize ( $value )

Parameters

mixed $value

Returns: string|integer

Definition at line 292 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	$key	Key to set value as
mixed	$value	Value 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 710 of file MemcachedClient.php.

References _set().

◆ set_compress_threshold()

MemcachedClient::set_compress_threshold ( $thresh )

Set the compression threshold.

Parameters

int $thresh Threshold to compress if larger than

Definition at line 744 of file MemcachedClient.php.

◆ set_debug()

MemcachedClient::set_debug ( $dbg )

Set the debug flag.

See also: __construct()

Parameters

bool $dbg True for debugging, false otherwise

Definition at line 757 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 $list Array of servers to connect to

Definition at line 770 of file MemcachedClient.php.

Referenced by __construct().

◆ set_timeout()

MemcachedClient::set_timeout	(		$seconds,
			$microseconds )

Sets the timeout for new connections.

Parameters

int	$seconds	Number of seconds
int	$microseconds	Number of microseconds

Definition at line 788 of file MemcachedClient.php.

◆ sock_to_host()

MemcachedClient::sock_to_host ( $host )

Returns the socket for the host.

Parameters

string $host Host:IP to get socket for

Returns: Resource|bool IO Stream or false

Access: private

Definition at line 1210 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	$time	TTL in seconds

Returns: bool True on success, false on failure

Definition at line 400 of file MemcachedClient.php.

References _debugprint(), _fgets(), _fwrite(), and get_sock().

◆ unserialize()

MemcachedClient::unserialize ( $value )

Parameters

string $value

Returns: mixed

Definition at line 300 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 217 of file MemcachedClient.php.

◆ $_bucketcount

int MemcachedClient::$_bucketcount

Total # of bit buckets we have.

Access: private

Definition at line 209 of file MemcachedClient.php.

◆ $_buckets

array MemcachedClient::$_buckets

Our bit buckets.

Access: private

Definition at line 201 of file MemcachedClient.php.

◆ $_cache_sock

array MemcachedClient::$_cache_sock

Cached Sockets that are connected.

Access: private

Definition at line 129 of file MemcachedClient.php.

◆ $_compress_enable

bool MemcachedClient::$_compress_enable

Do we want to use compression?

Access: private

Definition at line 161 of file MemcachedClient.php.

◆ $_compress_threshold

int MemcachedClient::$_compress_threshold

At how many bytes should we compress?

Access: private

Definition at line 169 of file MemcachedClient.php.

◆ $_connect_attempts

MemcachedClient::$_connect_attempts

Number of connection attempts for each server.

Definition at line 243 of file MemcachedClient.php.

◆ $_connect_timeout

MemcachedClient::$_connect_timeout

Connect timeout in seconds.

Definition at line 238 of file MemcachedClient.php.

◆ $_debug

bool MemcachedClient::$_debug

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

Access: private

Definition at line 137 of file MemcachedClient.php.

◆ $_have_zlib

bool MemcachedClient::$_have_zlib

Is compression available?

Access: private

Definition at line 153 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 145 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 246 of file MemcachedClient.php.

◆ $_persistent

bool MemcachedClient::$_persistent

Are we using persistent links?

Access: private

Definition at line 177 of file MemcachedClient.php.

◆ $_servers

array MemcachedClient::$_servers

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

Access: private

Definition at line 193 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 185 of file MemcachedClient.php.

◆ $_timeout_microseconds

int MemcachedClient::$_timeout_microseconds

Stream timeout in microseconds.

Access: private

Definition at line 233 of file MemcachedClient.php.

◆ $_timeout_seconds

int MemcachedClient::$_timeout_seconds

Stream timeout in seconds.

Applies for example to fread()

Access: private

Definition at line 225 of file MemcachedClient.php.

◆ $stats

array MemcachedClient::$stats

Command statistics.

Access: public

Definition at line 118 of file MemcachedClient.php.

◆ COMPRESSED

const MemcachedClient::COMPRESSED = 2

Flag: indicates data is compressed.

Definition at line 96 of file MemcachedClient.php.

◆ COMPRESSION_SAVINGS

const MemcachedClient::COMPRESSION_SAVINGS = 0.20

Minimum savings to store data compressed.

Definition at line 108 of file MemcachedClient.php.

◆ INTVAL

const MemcachedClient::INTVAL = 4

Flag: indicates data is an integer.

Definition at line 101 of file MemcachedClient.php.

◆ SERIALIZED

const MemcachedClient::SERIALIZED = 1

Flag: indicates data is serialized.

Definition at line 91 of file MemcachedClient.php.

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

includes/libs/objectcache/utils/MemcachedClient.php

Public Member Functions

Public Attributes

Detailed Description

Constructor & Destructor Documentation

◆ __construct()

Member Function Documentation

◆ _close_sock()

◆ _connect_sock()

◆ _dead_host()

◆ _dead_sock()

◆ _debugprint()

◆ _error_log()

◆ _fgets()

◆ _flush_read_buffer()

◆ _fread()

◆ _fwrite()

◆ _handle_error()

◆ _hashfunc()

◆ _incrdecr()

◆ _load_items()

◆ _set()

◆ add()

◆ cas()

◆ decr()

◆ delete()

◆ disconnect_all()

◆ enable_compress()

◆ forget_dead_hosts()

◆ get()

◆ get_multi()

◆ get_sock()

◆ incr()

◆ replace()

◆ run_command()

◆ serialize()

◆ set()

◆ set_compress_threshold()

◆ set_debug()

◆ set_servers()

◆ set_timeout()

◆ sock_to_host()

◆ touch()

◆ unserialize()

Member Data Documentation

◆ $_active

of total servers we have

◆ $_bucketcount

◆ $_buckets

◆ $_cache_sock

◆ $_compress_enable

◆ $_compress_threshold

◆ $_connect_attempts

◆ $_connect_timeout

◆ $_debug

◆ $_have_zlib

◆ $_host_dead

◆ $_last_cmd_status

◆ $_persistent

◆ $_servers

◆ $_single_sock

◆ $_timeout_microseconds

◆ $_timeout_seconds

◆ $stats

◆ COMPRESSED

◆ COMPRESSION_SAVINGS

◆ INTVAL

◆ SERIALIZED