MemCacheClient Class Reference

Public client interface for memcached. More...

#include <MemCacheClient.h>

List of all members.

std::vector< Server * > m_rgpServer

current servers

int m_nTimeoutMs

network timeout in millisec for all operations

std::vector< ConsistentHash > m_rgServerHash

Consistent hash ring for servers.

unsigned long CreateKeyHash (const char *a_pszKey)

Server * FindServer (const string_t &a_sKey)

int Store (const char *a_pszType, MemRequest *a_rgItem, int a_nCount)

void HandleStoreResponse (Server *a_pServer, MemRequest &a_oItem)

int Combine (const char *a_pszType, MemRequest *a_rgItem, int a_nCount)

int HandleGetResponse (Server *a_pServer, MemRequest **a_ppBegin, MemRequest **a_ppEnd)

int HandleDelResponse (Server *a_pServer, MemRequest **a_ppBegin, MemRequest **a_ppEnd)

MCResult IncDec (const char *a_pszType, const char *a_pszKey, uint64_t *a_pnNewValue, uint64_t a_nDiff, bool a_bWantReply)

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 (const MemCacheClient &)

Initialise the memcached client with copy.

MemCacheClient & operator= (const MemCacheClient &)

Copy another client.

~MemCacheClient ()

Destructor.

void SetTimeout (int a_nTimeoutMs)

Set the network timeout for all operations.

Servers

bool AddServer (const char *a_pszServer)

Add a server to the client.

bool DelServer (const char *a_pszServer)

Delete a server from the client.

void GetServers (std::vector< string_t > &a_rgServers)

Request the list of current servers.

void ClearServers ()

Disconnect from and remove all servers.

Single Requests

int Add (MemRequest &a_oItem)

Add an item to the cache.

int Set (MemRequest &a_oItem)

Set an item to the cache.

int Replace (MemRequest &a_oItem)

Replace an item in the cache.

int Append (MemRequest &a_oItem)

Append data to an existing item in the cache.

int Prepend (MemRequest &a_oItem)

Prepend data to an existing item in the cache.

int CheckSet (MemRequest &a_oItem)

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

int Get (MemRequest &a_oItem)

Get an item from the cache.

int Gets (MemRequest &a_oItem)

Get an item from the cache including the CAS data.

int Del (MemRequest &a_oItem)

Delete an item from the cache.

MCResult Increment (const char *a_pszKey, uint64_t *a_pnNewValue=NULL, uint64_t a_nDiff=1, bool a_bWantReply=true)

Increment a value at the server.

MCResult Decrement (const char *a_pszKey, uint64_t *a_pnNewValue=NULL, uint64_t a_nDiff=1, bool a_bWantReply=true)

Decrement a value at the server.

Multiple Requests

int Add (MemRequest *a_rgItem, int a_nCount)

Add multiple items to the cache.

int Set (MemRequest *a_rgItem, int a_nCount)

Set multiple items to the cache.

int Replace (MemRequest *a_rgItem, int a_nCount)

Replace multiple items in the cache.

int Append (MemRequest *a_rgItem, int a_nCount)

Append data to multiple existing items in the cache.

int Prepend (MemRequest *a_rgItem, int a_nCount)

Prepend data to multiple existing items in the cache.

int CheckSet (MemRequest *a_rgItem, int a_nCount)

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

int Get (MemRequest *a_rgItem, int a_nCount)

Get an item from the cache.

int Gets (MemRequest *a_rgItem, int a_nCount)

Get multiple items from the cache including the CAS data.

int Del (MemRequest *a_rgItem, int a_nCount)

Delete multiple items from the cache.

int FlushAll (const char *a_pszServer=NULL, int a_nExpiry=0)

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

Static Public Attributes

static const int MAX_REQUESTS = 20

Maximum number of request objects in a single call.

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...

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 127 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 129 of file MemCacheClient.h.

Constructor & Destructor Documentation

MemCacheClient::~MemCacheClient ( )

Destructor.

All servers will be disconnected.

Definition at line 489 of file MemCacheClient.cpp.

References ClearServers().

Member Function Documentation

MemCacheClient & MemCacheClient::operator= ( const MemCacheClient & rhs )

Copy another client.

All existing servers will be disconnected and removed. New connections will be created for all of the servers copied from the second client.

Definition at line 475 of file MemCacheClient.cpp.

References ClearServers(), m_nTimeoutMs, and m_rgpServer.

Referenced by MemCacheClient().

void MemCacheClient::SetTimeout ( int a_nTimeoutMs )

Set the network timeout for all operations.

All network operations share the same timeout.

Parameters:

a_nTimeoutMs

Timeout in milliseconds

Definition at line 613 of file MemCacheClient.cpp.

References m_nTimeoutMs.

bool MemCacheClient::AddServer ( const char * a_pszServer )

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:

a_pszServer

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

Returns:: true if server was added

Definition at line 504 of file MemCacheClient.cpp.

References CreateKeyHash(), MemCacheClient::Server::GetAddress(), m_rgpServer, m_rgServerHash, MemCacheClient::ConsistentHash::mHash, and MemCacheClient::Server::Set().

bool MemCacheClient::DelServer ( const char * a_pszServer )

Delete a server from the client.

The server should be specified as documented in AddServer.

Parameters:

a_pszServer

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 574 of file MemCacheClient.cpp.

References m_rgpServer, m_rgServerHash, and MemCacheClient::Server::Set().

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

Request the list of current servers.

Parameters:

a_rgServers

list of all servers registered to this client

Definition at line 601 of file MemCacheClient.cpp.

References m_rgpServer.

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

Add an item to the cache.

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

Parameters:

a_oItem

Item to be added

Returns:: Number of items with a success result.

Definition at line 279 of file MemCacheClient.h.

References Store().

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

Set an item to the cache.

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

Parameters:

a_oItem

Item to be updated

Returns:: Number of items with a success result.

Definition at line 289 of file MemCacheClient.h.

References Store().

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

Replace an item in the cache.

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

Parameters:

a_oItem

Item to be updated

Returns:: Number of items with a success result.

Definition at line 298 of file MemCacheClient.h.

References Store().

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

Append data to an existing item in the cache.

Parameters:

a_oItem

Item to be updated

Returns:: Number of items with a success result.

Definition at line 305 of file MemCacheClient.h.

References Store().

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

Prepend data to an existing item in the cache.

Parameters:

a_oItem

Item to be updated

Returns:: Number of items with a success result.

Definition at line 312 of file MemCacheClient.h.

References Store().

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

Set the data to an existing item in the cache 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:

a_oItem

Item to be updated

Returns:: Number of items with a success result.

Definition at line 323 of file MemCacheClient.h.

References Store().

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

Get an item from the cache.

Parameters:

a_oItem

Item to be retrieved

Returns:: Number of items with a success result.

Definition at line 330 of file MemCacheClient.h.

References Combine().

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

Get an item from the cache including the CAS data.

Parameters:

a_oItem

Item to be retrieved

Returns:: Number of items with a success result.

Definition at line 337 of file MemCacheClient.h.

References Combine().

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

Delete an item from the cache.

Parameters:

a_oItem

Item to be removed.

Returns:: Number of items with a success result.

Definition at line 344 of file MemCacheClient.h.

References Combine().

MCResult MemCacheClient::Increment	(	const char *	a_pszKey,
		uint64_t *	a_pnNewValue = `NULL`,
		uint64_t	a_nDiff = `1`,
		bool	a_bWantReply = `true`
	)			`[inline]`

Increment a value at the server.

See the INCR command in the memcached protocol.

Parameters:

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

Returns:: MCResult

Definition at line 360 of file MemCacheClient.h.

References IncDec().

MCResult MemCacheClient::Decrement	(	const char *	a_pszKey,
		uint64_t *	a_pnNewValue = `NULL`,
		uint64_t	a_nDiff = `1`,
		bool	a_bWantReply = `true`
	)			`[inline]`

Decrement a value at the server.

See the DECR command in the memcached protocol.

Parameters:

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

Returns:: MCResult

Definition at line 377 of file MemCacheClient.h.

References IncDec().

int MemCacheClient::Add	(	MemRequest *	a_rgItem,
		int	a_nCount
	)			`[inline]`

Add multiple items to the cache.

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:

	a_rgItem	Array of items to be added
	a_nCount	Number of items in the array

Returns:: Number of items with a success result

Definition at line 396 of file MemCacheClient.h.

References Store().

int MemCacheClient::Set	(	MemRequest *	a_rgItem,
		int	a_nCount
	)			`[inline]`

Set multiple items to the cache.

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:

	a_rgItem	Array of items to be added
	a_nCount	Number of items in the array

Returns:: Number of items with a success result

Definition at line 409 of file MemCacheClient.h.

References Store().

int MemCacheClient::Replace	(	MemRequest *	a_rgItem,
		int	a_nCount
	)			`[inline]`

Replace multiple items in the cache.

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:

	a_rgItem	Array of items to be added
	a_nCount	Number of items in the array

Returns:: Number of items with a success result

Definition at line 422 of file MemCacheClient.h.

References Store().

int MemCacheClient::Append	(	MemRequest *	a_rgItem,
		int	a_nCount
	)			`[inline]`

Append data to multiple existing items in the cache.

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

Parameters:

	a_rgItem	Array of items to be added
	a_nCount	Number of items in the array

Returns:: Number of items with a success result

Definition at line 433 of file MemCacheClient.h.

References Store().

int MemCacheClient::Prepend	(	MemRequest *	a_rgItem,
		int	a_nCount
	)			`[inline]`

Prepend data to multiple existing items in the cache.

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

Parameters:

	a_rgItem	Array of items to be added
	a_nCount	Number of items in the array

Returns:: Number of items with a success result

Definition at line 444 of file MemCacheClient.h.

References Store().

int MemCacheClient::CheckSet	(	MemRequest *	a_rgItem,
		int	a_nCount
	)			`[inline]`

Set the data to multiple existing items in the cache 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:

	a_rgItem	Array of items to be added
	a_nCount	Number of items in the array

Returns:: Number of items with a success result

Definition at line 459 of file MemCacheClient.h.

References Store().

int MemCacheClient::Get	(	MemRequest *	a_rgItem,
		int	a_nCount
	)			`[inline]`

Get an item from the cache.

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

Parameters:

	a_rgItem	Array of items to be retrieved
	a_nCount	Number of items in the array

Returns:: Number of items with a success result

Definition at line 470 of file MemCacheClient.h.

References Combine().

int MemCacheClient::Gets	(	MemRequest *	a_rgItem,
		int	a_nCount
	)			`[inline]`

Get multiple items from the cache 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:

	a_rgItem	Array of items to be retrieved
	a_nCount	Number of items in the array

Returns:: Number of items with a success result

Definition at line 481 of file MemCacheClient.h.

References Combine().

int MemCacheClient::Del	(	MemRequest *	a_rgItem,
		int	a_nCount
	)			`[inline]`

Delete multiple items from the cache.

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

Parameters:

	a_rgItem	Array of items to be retrieved
	a_nCount	Number of items in the array

Returns:: Number of items with a success result

Definition at line 492 of file MemCacheClient.h.

References Combine().

int MemCacheClient::FlushAll	(	const char *	a_pszServer = `NULL`,
		int	a_nExpiry = `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:

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

Returns:: Number of servers that were flushed.

Definition at line 1067 of file MemCacheClient.cpp.

References MemCacheClient::Server::Connect(), ServerSocket::Disconnect(), ServerSocket::GetByte(), m_nTimeoutMs, m_rgpServer, ServerSocket::SendBytes(), and MemCacheClient::Server::Set().

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

create a hash value from the key

Definition at line 621 of file MemCacheClient.cpp.

Referenced by AddServer(), and FindServer().

MemCacheClient::Server * MemCacheClient::FindServer ( const string_t & a_sKey ) [private]

find which server will be used to handle the key

Definition at line 637 of file MemCacheClient.cpp.

References MemCacheClient::Server::Connect(), CreateKeyHash(), m_nTimeoutMs, and m_rgServerHash.

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

int MemCacheClient::Store	(	const char *	a_pszType,
		MemRequest *	a_rgItem,
		int	a_nCount
	)			`[private]`

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

Definition at line 958 of file MemCacheClient.cpp.

References ReadWriteBuffer::CommitReadBytes(), FindServer(), ReadWriteBuffer::GetReadSize(), HandleStoreResponse(), MCERR_NOREPLY, MCERR_NOSERVER, MemCacheClient::MemRequest::mData, MemCacheClient::MemRequest::mKey, MemCacheClient::MemRequest::mResult, MemCacheClient::MemRequest::mServer, and ServerSocket::SendBytes().

Referenced by Add(), Append(), CheckSet(), Prepend(), Replace(), and Set().

void MemCacheClient::HandleStoreResponse	(	Server *	a_pServer,
		MemRequest &	a_oItem
	)			`[private]`

handle a single storage response from a server

Definition at line 1034 of file MemCacheClient.cpp.

References ServerSocket::Disconnect(), ServerSocket::GetByte(), MCERR_NOTSTORED, MCERR_OK, and MemCacheClient::MemRequest::mResult.

Referenced by Store().

int MemCacheClient::Combine	(	const char *	a_pszType,
		MemRequest *	a_rgItem,
		int	a_nCount
	)			`[private]`

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

Definition at line 676 of file MemCacheClient.cpp.

References ServerSocket::Disconnect(), FindServer(), HandleDelResponse(), HandleGetResponse(), MAX_REQUESTS, MCERR_NOREPLY, MCERR_NOSERVER, MCERR_NOTFOUND, MemCacheClient::MemRequest::mKey, MemCacheClient::MemRequest::mResult, MemCacheClient::MemRequest::mServer, and ServerSocket::SendBytes().

Referenced by Del(), Get(), and Gets().

int MemCacheClient::HandleGetResponse	(	Server *	a_pServer,
		MemRequest **	a_ppBegin,
		MemRequest **	a_ppEnd
	)			`[private]`

handle a single get or gets response from a server

Definition at line 789 of file MemCacheClient.cpp.

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

Referenced by Combine().

int MemCacheClient::HandleDelResponse	(	Server *	a_pServer,
		MemRequest **	a_ppBegin,
		MemRequest **	a_ppEnd
	)			`[private]`

handle a single del response from a server

Definition at line 865 of file MemCacheClient.cpp.

References ServerSocket::Disconnect(), ServerSocket::GetByte(), MCERR_NOREPLY, MCERR_NOTFOUND, MCERR_OK, and MemCacheClient::MemRequest::mResult.

Referenced by Combine().

MCResult MemCacheClient::IncDec	(	const char *	a_pszType,
		const char *	a_pszKey,
		uint64_t *	a_pnNewValue,
		uint64_t	a_nDiff,
		bool	a_bWantReply
	)			`[private]`

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

Definition at line 907 of file MemCacheClient.cpp.

References ServerSocket::Disconnect(), FindServer(), ServerSocket::GetByte(), MCERR_NOREPLY, MCERR_NOSERVER, MCERR_NOTFOUND, MCERR_OK, and ServerSocket::SendBytes().

Referenced by Decrement(), and Increment().

Member Data Documentation

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

Consistent hash ring for servers.

This vector is in sorted order on the hash key.

Definition at line 550 of file MemCacheClient.h.

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

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


std::vector< Server * >	m_rgpServer
	current servers
int	m_nTimeoutMs
	network timeout in millisec for all operations
std::vector< ConsistentHash >	m_rgServerHash
	Consistent hash ring for servers.
unsigned long	CreateKeyHash (const char *a_pszKey)
Server *	FindServer (const string_t &a_sKey)
int	Store (const char a_pszType, MemRequest a_rgItem, int a_nCount)
void	HandleStoreResponse (Server *a_pServer, MemRequest &a_oItem)
int	Combine (const char a_pszType, MemRequest a_rgItem, int a_nCount)
int	HandleGetResponse (Server a_pServer, MemRequest a_ppBegin, MemRequest *a_ppEnd)
int	HandleDelResponse (Server a_pServer, MemRequest a_ppBegin, MemRequest *a_ppEnd)
MCResult	IncDec (const char a_pszType, const char a_pszKey, uint64_t *a_pnNewValue, uint64_t a_nDiff, bool a_bWantReply)
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 (const MemCacheClient &)
	Initialise the memcached client with copy.
MemCacheClient &	operator= (const MemCacheClient &)
	Copy another client.
	~MemCacheClient ()
	Destructor.
void	SetTimeout (int a_nTimeoutMs)
	Set the network timeout for all operations.
Servers

bool	AddServer (const char *a_pszServer)
	Add a server to the client.
bool	DelServer (const char *a_pszServer)
	Delete a server from the client.
void	GetServers (std::vector< string_t > &a_rgServers)
	Request the list of current servers.
void	ClearServers ()
	Disconnect from and remove all servers.
Single Requests

int	Add (MemRequest &a_oItem)
	Add an item to the cache.
int	Set (MemRequest &a_oItem)
	Set an item to the cache.
int	Replace (MemRequest &a_oItem)
	Replace an item in the cache.
int	Append (MemRequest &a_oItem)
	Append data to an existing item in the cache.
int	Prepend (MemRequest &a_oItem)
	Prepend data to an existing item in the cache.
int	CheckSet (MemRequest &a_oItem)
	Set the data to an existing item in the cache only if it has not been modified since it was last retrieved.
int	Get (MemRequest &a_oItem)
	Get an item from the cache.
int	Gets (MemRequest &a_oItem)
	Get an item from the cache including the CAS data.
int	Del (MemRequest &a_oItem)
	Delete an item from the cache.
MCResult	Increment (const char a_pszKey, uint64_t a_pnNewValue=NULL, uint64_t a_nDiff=1, bool a_bWantReply=true)
	Increment a value at the server.
MCResult	Decrement (const char a_pszKey, uint64_t a_pnNewValue=NULL, uint64_t a_nDiff=1, bool a_bWantReply=true)
	Decrement a value at the server.
Multiple Requests

int	Add (MemRequest *a_rgItem, int a_nCount)
	Add multiple items to the cache.
int	Set (MemRequest *a_rgItem, int a_nCount)
	Set multiple items to the cache.
int	Replace (MemRequest *a_rgItem, int a_nCount)
	Replace multiple items in the cache.
int	Append (MemRequest *a_rgItem, int a_nCount)
	Append data to multiple existing items in the cache.
int	Prepend (MemRequest *a_rgItem, int a_nCount)
	Prepend data to multiple existing items in the cache.
int	CheckSet (MemRequest *a_rgItem, int a_nCount)
	Set the data to multiple existing items in the cache only if it has not been modified since it was last retrieved.
int	Get (MemRequest *a_rgItem, int a_nCount)
	Get an item from the cache.
int	Gets (MemRequest *a_rgItem, int a_nCount)
	Get multiple items from the cache including the CAS data.
int	Del (MemRequest *a_rgItem, int a_nCount)
	Delete multiple items from the cache.
int	FlushAll (const char *a_pszServer=NULL, int a_nExpiry=0)
	Send a flush_all command to a specific server or all servers.
Static Public Attributes
static const int	MAX_REQUESTS = 20
	Maximum number of request objects in a single call.
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...