Public client interface for memcached. More...

#include <MemCacheClient.h>

Classes
struct	ConsistentHash
	Maintain the N:1 hash key to server relationship used for consistent hashing. More...
struct	MemRequest
	Input and output structure for most requests to the server. More...
class	Server
	Abstraction of a server connection. More...
Public Types
typedef std::string	string_t
	server connection implementation
typedef unsigned __int64	uint64_t
	64-bit unsigned type
Public Member Functions
	MemCacheClient ()
	Initialise the memcached client.
	~MemCacheClient ()
	Destructor.
void	SetTimeout (size_t aTimeoutMs)
	Set the network timeout for all operations.
void	SetRetryPeriod (size_t aRetryMs)
	Set the period to wait before trying to reconnect to a server that isn't available.
void	DumpTables ()
	dump internal tables to trace log
Servers
bool	AddServer (const char aServerAddress, const char aServerName=NULL, unsigned aServices=(unsigned)-1)
	Add a server to the client.
bool	DelServer (const char *aServerAddress)
	Delete a server from the client.
void	GetServers (std::vector< string_t > &aServers)
	Request the list of current servers.
void	ClearServers ()
	Disconnect from and remove all servers.
Single Requests
int	Add (MemRequest &aItem)
	Add an item to the server.
int	Set (MemRequest &aItem)
	Set an item to the server.
int	Replace (MemRequest &aItem)
	Replace an item in the server.
int	Append (MemRequest &aItem)
	Append data to an existing item in the server.
int	Prepend (MemRequest &aItem)
	Prepend data to an existing item in the server.
int	CheckSet (MemRequest &aItem)
	Set the data to an existing item in the server only if it has not been modified since it was last retrieved.
int	Get (MemRequest &aItem)
	Get an item from the server.
int	Gets (MemRequest &aItem)
	Get an item from the server including the CAS data.
int	Del (MemRequest &aItem)
	Delete an item from the server.
MCResult	Increment (const char aKey, uint64_t aNewValue=NULL, uint64_t aDiff=1, bool aWantReply=true, unsigned aService=0)
	Increment a value at the server.
MCResult	Decrement (const char aKey, uint64_t aNewValue=NULL, uint64_t aDiff=1, bool aWantReply=true, unsigned aService=0)
	Decrement a value at the server.
Multiple Requests
int	Add (MemRequest *aItem, int aCount)
	Add multiple items to the server.
int	Set (MemRequest *aItem, int aCount)
	Set multiple items to the server.
int	Replace (MemRequest *aItem, int aCount)
	Replace multiple items in the server.
int	Append (MemRequest *aItem, int aCount)
	Append data to multiple existing items in the server.
int	Prepend (MemRequest *aItem, int aCount)
	Prepend data to multiple existing items in the server.
int	CheckSet (MemRequest *aItem, int aCount)
	Set the data to multiple existing items in the server only if it has not been modified since it was last retrieved.
int	Get (MemRequest *aItem, int aCount)
	Get an item from the server.
int	Gets (MemRequest *aItem, int aCount)
	Get multiple items from the server including the CAS data.
int	Del (MemRequest *aItem, int aCount)
	Delete multiple items from the server.
int	FlushAll (const char *aServer=NULL, int aExpiry=0)
	Send a flush_all command to a specific server or all servers.
Static Public Member Functions
static const char *	ConvertResult (MCResult aResult)
	turn a result code into a string
Static Public Attributes
static const int	MAX_REQUESTS = 50
	Maximum number of request objects in a single call.
Private Member Functions
	MemCacheClient (const MemCacheClient &)
MemCacheClient &	operator= (const MemCacheClient &)

ClTrace	mTrace
std::vector< Server * >	mServer
	current servers
size_t	mTimeoutMs
	network timeout in millisec for all operations
size_t	mRetryMs
	retry period in millisec for unavailable servers
std::vector< ConsistentHash >	mServerHash
	Consistent hash ring for servers.
unsigned long	CreateKeyHash (const char *aKey)
Server *	FindServer (const string_t &aKey, unsigned aService)
int	Store (const char aType, MemRequest aItem, int aCount)
void	HandleStoreResponse (Server *aServer, MemRequest &aItem)
int	Combine (const char aType, MemRequest aItem, int aCount)
int	HandleGetResponse (Server aServer, MemRequest aBegin, MemRequest *aEnd)
int	HandleDelResponse (Server aServer, MemRequest aBegin, MemRequest *aEnd)
MCResult	IncDec (const char aType, unsigned aService, const char aKey, uint64_t *aNewValue, uint64_t aDiff, bool aWantReply)

Detailed Description

Public client interface for memcached.

Create an instance of this class, add all servers to it and then call request methods. A single instance of the client is not threadsafe. Use explicit locking or an instance per thread. Each instance will maintain a single TCP socket open to each server.

Definition at line 137 of file MemCacheClient.h.

Member Typedef Documentation

typedef std::string MemCacheClient::string_t

server connection implementation

Abstract the string class for internal use

Definition at line 139 of file MemCacheClient.h.

Constructor & Destructor Documentation

MemCacheClient::~MemCacheClient ( )

Destructor.

All servers will be disconnected.

Definition at line 255 of file MemCacheClient.cpp.

References ClearServers().

Member Function Documentation

int MemCacheClient::Add ( MemRequest & aItem ) [inline]

Add an item to the server.

This will fail if the item already exists at the server.

Parameters:

aItem Item to be added

Returns:: Number of items with a success result.

Definition at line 308 of file MemCacheClient.h.

int MemCacheClient::Add	(	MemRequest *	aItem,
		int	aCount
	)		`[inline]`

Add multiple items to the server.

This will fail if the item already exists at the server.

Note:: Each request is independent of other requests in the array. Failure of one request does not imply failure of any other.

Parameters:

aItem	Array of items to be added
aCount	Number of items in the array

Returns:: Number of items with a success result

Definition at line 425 of file MemCacheClient.h.

bool MemCacheClient::AddServer	(	const char *	aServerAddress,
		const char *	aServerName = `NULL`,
		unsigned	aServices = `(unsigned)-1`
	)

Add a server to the client.

This function will fail only if the address is not a valid IP address or PORT. It will not fail if the server cannot be contacted but will instead continue to occasionally attempt connections to that server.

Parameters:

aServerAddress	The memcached server to be as IP[:PORT]. The port will default to 11211 if not supplied.
aServerName	Display name for the server. Default is aServerAddress.
aServiceFlags	The type of services this server is used for. When looking up a server to be used, only servers that have a matching bit in these flags will be used. See SetRequiredService().

Returns:: true if server was added

Definition at line 285 of file MemCacheClient.cpp.

References CreateKeyHash(), MemCacheClient::Server::GetAddress(), MemCacheClient::Server::GetPort(), MemCacheClient::ConsistentHash::mEntry, MemCacheClient::ConsistentHash::mHash, mServer, mServerHash, and MemCacheClient::Server::Set().

int MemCacheClient::Append	(	MemRequest *	aItem,
		int	aCount
	)		`[inline]`

Append data to multiple existing items in the server.

Note:: Each request is independent of other requests in the array. Failure of one request does not imply failure of any other.

Parameters:

aItem	Array of items to be added
aCount	Number of items in the array

Returns:: Number of items with a success result

Definition at line 462 of file MemCacheClient.h.

int MemCacheClient::Append ( MemRequest & aItem ) [inline]

Append data to an existing item in the server.

Parameters:

aItem Item to be updated

Returns:: Number of items with a success result.

Definition at line 334 of file MemCacheClient.h.

int MemCacheClient::CheckSet	(	MemRequest *	aItem,
		int	aCount
	)		`[inline]`

Set the data to multiple existing items in the server only if it has not been modified since it was last retrieved.

This requires the mCas member to be set in the request. Use the Gets command to retrieve an item with a valid mCas member.

Note:: Each request is independent of other requests in the array. Failure of one request does not imply failure of any other.

Parameters:

aItem	Array of items to be added
aCount	Number of items in the array

Returns:: Number of items with a success result

Definition at line 488 of file MemCacheClient.h.

int MemCacheClient::CheckSet ( MemRequest & aItem ) [inline]

Set the data to an existing item in the server only if it has not been modified since it was last retrieved.

This requires the mCas member to be set in the request. Use the Gets command to retrieve an item with a valid mCas member.

Parameters:

aItem Item to be updated

Returns:: Number of items with a success result.

Definition at line 352 of file MemCacheClient.h.

int MemCacheClient::Combine	(	const char *	aType,
		MemRequest *	aItem,
		int	aCount
	)		`[private]`

send multiple commands to all servers for commands that can be combined (get, gets, del)

Definition at line 515 of file MemCacheClient.cpp.

References Socket::Disconnect(), FindServer(), MemCacheClient::Server::GetAddress(), HandleDelResponse(), HandleGetResponse(), MAX_REQUESTS, MCERR_NOREPLY, MCERR_NOSERVER, MCERR_NOTFOUND, MemCacheClient::MemRequest::mData, Socket::Exception::mDetail, MemCacheClient::MemRequest::mKey, MemCacheClient::MemRequest::mResult, mServer, MemCacheClient::MemRequest::mServer, Socket::SendBytes(), and ReadWriteBuffer::SetEmpty().

unsigned long MemCacheClient::CreateKeyHash ( const char * aKey ) [private]

create a hash value from the key

Definition at line 424 of file MemCacheClient.cpp.

Referenced by AddServer(), DumpTables(), and FindServer().

MCResult MemCacheClient::Decrement	(	const char *	aKey,
		uint64_t *	aNewValue = `NULL`,
		uint64_t	aDiff = `1`,
		bool	aWantReply = `true`,
		unsigned	aService = `0`
	)		`[inline]`

Decrement a value at the server.

See the DECR command in the memcached protocol.

Parameters:

aKey	Key to decrement
aNewValue	Receive the new value if desired. If aWantReply is false, this value will not be updated. If aWantReply is true, a reply will stil be requested from the server even if this item is NULL.
aDiff	Positive integer to decrement the value at the server by.
aWantReply	Should a reply be requested from the server.

Returns:: MCResult

Definition at line 406 of file MemCacheClient.h.

int MemCacheClient::Del ( MemRequest & aItem ) [inline]

Delete an item from the server.

Parameters:

aItem Item to be removed.

Returns:: Number of items with a success result.

Definition at line 373 of file MemCacheClient.h.

int MemCacheClient::Del	(	MemRequest *	aItem,
		int	aCount
	)		`[inline]`

Delete multiple items from the server.

Note:: Each request is independent of other requests in the array. Failure of one request does not imply failure of any other.

Parameters:

aItem	Array of items to be retrieved
aCount	Number of items in the array

Returns:: Number of items with a success result

Definition at line 521 of file MemCacheClient.h.

bool MemCacheClient::DelServer ( const char * aServerAddress )

Delete a server from the client.

The server should be specified as documented in AddServer.

Parameters:

aServerAddress The server to be added specified as IP[:PORT]. The port will default to 11211 if not supplied.

Returns:: true if server was deleted

Definition at line 367 of file MemCacheClient.cpp.

References mServer, mServerHash, and MemCacheClient::Server::Set().

MemCacheClient::Server * MemCacheClient::FindServer	(	const string_t &	aKey,
		unsigned	aService
	)		`[private]`

find which server will be used to handle the key

Definition at line 443 of file MemCacheClient.cpp.

References MemCacheClient::Server::Connect(), CreateKeyHash(), mRetryMs, mServerHash, and mTimeoutMs.

Referenced by Combine(), IncDec(), and Store().

int MemCacheClient::FlushAll	(	const char *	aServer = `NULL`,
		int	aExpiry = `0`
	)

Send a flush_all command to a specific server or all servers.

Note:: Each request is independent of other requests in the array. Failure of one request does not imply failure of any other.

Parameters:

aServer	Server to flush. If NULL all servers will be flushed.
aExpiry	Expiry time for the flush. The server will wait before executing the server flush. See MemRequest::mExpiry for details of possible values.

Returns:: Number of servers that were flushed.

Definition at line 950 of file MemCacheClient.cpp.

References MemCacheClient::Server::Connect(), Socket::Disconnect(), Socket::GetByte(), mRetryMs, mServer, mTimeoutMs, Socket::SendBytes(), and MemCacheClient::Server::Set().

int MemCacheClient::Get	(	MemRequest *	aItem,
		int	aCount
	)		`[inline]`

Get an item from the server.

Note:: Each request is independent of other requests in the array. Failure of one request does not imply failure of any other.

Parameters:

aItem	Array of items to be retrieved
aCount	Number of items in the array

Returns:: Number of items with a success result

Definition at line 499 of file MemCacheClient.h.

int MemCacheClient::Get ( MemRequest & aItem ) [inline]

Get an item from the server.

Parameters:

aItem Item to be retrieved

Returns:: Number of items with a success result.

Definition at line 359 of file MemCacheClient.h.

int MemCacheClient::Gets ( MemRequest & aItem ) [inline]

Get an item from the server including the CAS data.

Parameters:

aItem Item to be retrieved

Returns:: Number of items with a success result.

Definition at line 366 of file MemCacheClient.h.

int MemCacheClient::Gets	(	MemRequest *	aItem,
		int	aCount
	)		`[inline]`

Get multiple items from the server including the CAS data.

Note:: Each request is independent of other requests in the array. Failure of one request does not imply failure of any other.

Parameters:

aItem	Array of items to be retrieved
aCount	Number of items in the array

Returns:: Number of items with a success result

Definition at line 510 of file MemCacheClient.h.

void MemCacheClient::GetServers ( std::vector< string_t > & aServers )

Request the list of current servers.

Parameters:

aServers list of all servers registered to this client

Definition at line 394 of file MemCacheClient.cpp.

References mServer.

int MemCacheClient::HandleDelResponse	(	Server *	aServer,
		MemRequest **	aBegin,
		MemRequest **	aEnd
	)		`[private]`

handle a single del response from a server

Definition at line 728 of file MemCacheClient.cpp.

References Socket::Disconnect(), MCERR_NOREPLY, MCERR_NOTFOUND, MCERR_OK, MemCacheClient::MemRequest::mResult, and Socket::ReceiveLine().

Referenced by Combine().

int MemCacheClient::HandleGetResponse	(	Server *	aServer,
		MemRequest **	aBegin,
		MemRequest **	aEnd
	)		`[private]`

handle a single get or gets response from a server

Definition at line 654 of file MemCacheClient.cpp.

References ReadWriteBuffer::CommitWriteBytes(), Socket::DiscardBytes(), Socket::GetByte(), Socket::GetBytes(), ReadWriteBuffer::GetWriteBuffer(), MemCacheClient::MemRequest::mCas, MCERR_OK, MemCacheClient::MemRequest::mData, MemCacheClient::MemRequest::mFlags, MemCacheClient::MemRequest::mResult, and Socket::ReceiveLine().

Referenced by Combine().

void MemCacheClient::HandleStoreResponse	(	Server *	aServer,
		MemRequest &	aItem
	)		`[private]`

handle a single storage response from a server

Definition at line 914 of file MemCacheClient.cpp.

References Socket::Disconnect(), MCERR_NOTSTORED, MCERR_OK, MemCacheClient::MemRequest::mResult, and Socket::ReceiveLine().

Referenced by Store().

MCResult MemCacheClient::IncDec	(	const char *	aType,
		unsigned	aService,
		const char *	aKey,
		uint64_t *	aNewValue,
		uint64_t	aDiff,
		bool	aWantReply
	)		`[private]`

send an incr or decr request to a server and handle the response

Definition at line 767 of file MemCacheClient.cpp.

References Socket::Disconnect(), FindServer(), MemCacheClient::Server::GetAddress(), Socket::GetByte(), MCERR_NOREPLY, MCERR_NOSERVER, MCERR_NOTFOUND, MCERR_OK, Socket::Exception::mDetail, and Socket::SendBytes().

MCResult MemCacheClient::Increment	(	const char *	aKey,
		uint64_t *	aNewValue = `NULL`,
		uint64_t	aDiff = `1`,
		bool	aWantReply = `true`,
		unsigned	aService = `0`
	)		`[inline]`

Increment a value at the server.

See the INCR command in the memcached protocol.

Parameters:

aKey	Key to increment
aNewValue	Receive the new value if desired. If aWantReply is false, this value will not be updated. If aWantReply is true, a reply will stil be requested from the server even if this item is NULL.
aDiff	Positive integer to increment the value at the server by.
aWantReply	Should a reply be requested from the server.

Returns:: MCResult

Definition at line 389 of file MemCacheClient.h.

int MemCacheClient::Prepend ( MemRequest & aItem ) [inline]

Prepend data to an existing item in the server.

Parameters:

aItem Item to be updated

Returns:: Number of items with a success result.

Definition at line 341 of file MemCacheClient.h.

int MemCacheClient::Prepend	(	MemRequest *	aItem,
		int	aCount
	)		`[inline]`

Prepend data to multiple existing items in the server.

Note:: Each request is independent of other requests in the array. Failure of one request does not imply failure of any other.

Parameters:

aItem	Array of items to be added
aCount	Number of items in the array

Returns:: Number of items with a success result

Definition at line 473 of file MemCacheClient.h.

int MemCacheClient::Replace ( MemRequest & aItem ) [inline]

Replace an item in the server.

This will fail if the item does not already exist at the server.

Parameters:

aItem Item to be updated

Returns:: Number of items with a success result.

Definition at line 327 of file MemCacheClient.h.

int MemCacheClient::Replace	(	MemRequest *	aItem,
		int	aCount
	)		`[inline]`

Replace multiple items in the server.

This will fail if the item does not already exist at the server.

Note:: Each request is independent of other requests in the array. Failure of one request does not imply failure of any other.

Parameters:

aItem	Array of items to be added
aCount	Number of items in the array

Returns:: Number of items with a success result

Definition at line 451 of file MemCacheClient.h.

int MemCacheClient::Set ( MemRequest & aItem ) [inline]

Set an item to the server.

This will always set the item at the server regardless of if it already exists or not.

Parameters:

aItem Item to be updated

Returns:: Number of items with a success result.

Definition at line 318 of file MemCacheClient.h.

int MemCacheClient::Set	(	MemRequest *	aItem,
		int	aCount
	)		`[inline]`

Set multiple items to the server.

This will always set the item at the server regardless of if it already exists or not.

Note:: Each request is independent of other requests in the array. Failure of one request does not imply failure of any other.

Parameters:

aItem	Array of items to be added
aCount	Number of items in the array

Returns:: Number of items with a success result

Definition at line 438 of file MemCacheClient.h.

void MemCacheClient::SetRetryPeriod ( size_t aRetryMs )

Set the period to wait before trying to reconnect to a server that isn't available.

Parameters:

aRetryMs Period in milliseconds

Definition at line 416 of file MemCacheClient.cpp.

References mRetryMs.

void MemCacheClient::SetTimeout ( size_t aTimeoutMs )

Set the network timeout for all operations.

All network operations share the same timeout.

Parameters:

aTimeoutMs Timeout in milliseconds

Definition at line 408 of file MemCacheClient.cpp.

References mTimeoutMs.

int MemCacheClient::Store	(	const char *	aType,
		MemRequest *	aItem,
		int	aCount
	)		`[private]`

send storage requests (add, set, cas, replace, append, prepend)

Definition at line 822 of file MemCacheClient.cpp.

References ReadWriteBuffer::CommitReadBytes(), FindServer(), MemCacheClient::Server::GetAddress(), ReadWriteBuffer::GetReadSize(), HandleStoreResponse(), MCERR_NOREPLY, MCERR_NOSERVER, MemCacheClient::MemRequest::mData, Socket::Exception::mDetail, MemCacheClient::MemRequest::mKey, MemCacheClient::MemRequest::mResult, mServer, MemCacheClient::MemRequest::mServer, and Socket::SendBytes().

Member Data Documentation

std::vector<ConsistentHash> MemCacheClient::mServerHash [private]

Consistent hash ring for servers.

This vector is in sorted order on the hash key.

Definition at line 592 of file MemCacheClient.h.

Referenced by AddServer(), DelServer(), DumpTables(), and FindServer().

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

MemCacheClient Class Reference

Classes

Public Types

Public Member Functions

Static Public Member Functions

Static Public Attributes

Private Member Functions

Detailed Description

Member Typedef Documentation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation