#include <evo/async/memcached_server.h>

Inheritance diagram for MemcachedServerHandlerBase:

Detailed Description

Base class for user defined Memcached server handler.

See: MemcachedServer

Request event methods:

Classes
struct	CommandEnum
	Command enum mappings. More...

struct	DeferredReply
	Deferred reply helper – deferred event objects should hold or inherit this, and use to send deferred response. More...

struct	GetAdvParams
	Additional parameters for advanced GET request variants. More...

struct	StoreParams
	STORE command parameters. More...

Public Types
enum	Command { cUNKNOWN = 0, cADD, cAPPEND, cCAS, cDECREMENT, cDELETE, cGAT, cGATS, cGET, cGETS, cINCREMENT, cPREPEND, cQUIT, cREPLACE, cSET, cSTATS, cTOUCH, cVERSION, cENUM_END }
	Command value. More...

typedef DeferredContextT< MemcachedServerHandlerBase >	DeferredContext
	Deferred context helper – used by AsyncServer. More...

typedef ResponseResult< GeneralResultValue >	DeleteResult
	DELETE command result returned by on_delete() More...

enum	GeneralResultValue { grOK, grNOT_FOUND }
	General result used by some commands. More...

typedef ResponseResult< GetStartResultValue >	GetStartResult
	GET command result returned by on_get_start() More...

enum	GetStartResultValue { gsrCONTINUE, gsrSKIP }
	GET command result from on_get_start(). More...

typedef ResponseResult< UInt64 >	IncrementResult
	INCR/DECR command result. More...

typedef evo::async::Memcached	Memcached
	Alias for `evo::async::Memcached` More...

enum	ResponseType { rtNORMAL, rtDEFERRED, rtHANDLED, rtCLOSE }
	Handler response type – used with ResponseResult. More...

typedef ResponseResult< Memcached::StoreResult >	StoreResult
	STORE command result returned by on_store() More...

typedef ResponseResult< GeneralResultValue >	TouchResult
	TOUCH command result returned by on_touch() More...

Public Member Functions
	MemcachedServerHandlerBase ()
	Constructor. More...

virtual bool	on_command (bool &handled, SubString &command_str, SubString &params)
	Called on any other command. More...

virtual DeleteResult	on_delete (DeferredContext &context, const SubString &key)
	Called on DELETE request to delete key and value. More...

virtual void	on_error (AsyncError err)
	Called on error. More...

virtual void	on_flush_all (ulong delay_sec)
	Called on FLUSH_ALL request to expire all keys. More...

virtual ResponseType	on_get (DeferredContext &context, const SubString &key, GetAdvParams *adv_params)
	Called for each key in GET request. More...

virtual ResponseType	on_get_end (DeferredContext &context)
	Called at end of GET request. More...

virtual GetStartResult	on_get_start (DeferredContext &context, const SubString &keys, GetAdvParams *adv_params)
	Called at the beginning of a GET request with all requested keys. More...

virtual IncrementResult	on_increment (DeferredContext &context, const SubString &key, uint64 count, bool decrement)
	Called on INCR or DECR request to increment or decrement a numeric value. More...

virtual void	on_stats (SubString &params)
	Called on STATS request for statistics. More...

virtual StoreResult	on_store (DeferredContext &context, StoreParams &params, SubString &value, Command command, uint64 cas_id)
	Called on STORE request to store a value. More...

virtual TouchResult	on_touch (DeferredContext &context, const SubString &key, int64 expire)
	Called on TOUCH request to update expiration of existing key without retrieving the value. More...

virtual void	on_version (String &version)
	Called on VERSION request for server version. More...

void	send_client_error (const SubString &msg)
	Helper to send a client error response. More...

void	send_error (const SubString &msg)
	Helper to send a server error response. More...

void	send_reply (const SubString &msg)
	Helper to send a reply message. More...

void	send_stat (const SubString &name, const SubString &value)
	Helper for sending statistics. More...

void	send_value (const SubString &key, const SubString &value, uint32 flags=0, uint64 *cas_id=NULL)
	Helper to send value for get response. More...

void	set_id ()
	Create and set new ID for current request/response. More...

Static Public Member Functions
static size_t	get_max_initial_read ()

Public Attributes
AsyncBuffers	buffers
	Buffers for async I/O. More...

bool	enable_cas
	Derived constructor must set to true to enable "compare and swap" (gets/gats command) More...

bool	enable_gat
	Derived constructor must set to true to enable "get and touch" (gat/gats command) More...

ulong	id
	Request/reply ID, used by reply manager (set by parent protocol class) More...

LoggerPtr	logger
	Logger to use (set by AsyncServer) More...

bool	noreply
	Whether no-reply mode is enabled (set by parent protocol class) More...

AsyncServerReply	reply
	Server reply manager, used to track deferred events and queue out of order replies. More...

Static Public Attributes
static const size_t	MAX_INITIAL_READ = 8192
	Max initial read size. More...

Member Typedef Documentation

◆ DeferredContext

typedef DeferredContextT<MemcachedServerHandlerBase> DeferredContext

Deferred context helper – used by AsyncServer.

◆ DeleteResult

typedef ResponseResult<GeneralResultValue> DeleteResult

DELETE command result returned by on_delete()

◆ GetStartResult

typedef ResponseResult<GetStartResultValue> GetStartResult

GET command result returned by on_get_start()

◆ IncrementResult

typedef ResponseResult<UInt64> IncrementResult

INCR/DECR command result.

◆ Memcached

typedef evo::async::Memcached Memcached

Alias for evo::async::Memcached

◆ StoreResult

typedef ResponseResult<Memcached::StoreResult> StoreResult

STORE command result returned by on_store()

◆ TouchResult

typedef ResponseResult<GeneralResultValue> TouchResult

TOUCH command result returned by on_touch()

Member Enumeration Documentation

◆ Command

enum Command

Command value.

Enumerator
cUNKNOWN	Unknown command (always first)
cADD	Add value if not found.
cAPPEND	Append to existing value.
cCAS	Compare and swap
cDECREMENT	Decrement numeric value for key.
cDELETE	Delete by key.
cGAT	Get value and update expiratiom time.
cGATS	Get value for compare and swap and update expiratiom time.
cGET	Get value.
cGETS	Get value for compare and swap.
cINCREMENT	Increment numeric value for key.
cPREPEND	Prepend to existing value.
cQUIT	Quit command to close connection.
cREPLACE	Replace value if found.
cSET	Set new value.
cSTATS	Get server stats.
cTOUCH	Touch key by updating expiration time.
cVERSION	Get server version.
cENUM_END	Enum guard value (always last)

◆ GeneralResultValue

enum GeneralResultValue

General result used by some commands.

Enumerator
grOK	Success.
grNOT_FOUND	Key not found.

◆ GetStartResultValue

enum GetStartResultValue

GET command result from on_get_start().

Enumerator
gsrCONTINUE	Continue to on_get() events.
gsrSKIP	Skip on_get() events.

◆ ResponseType

enum ResponseType

inherited

Handler response type – used with ResponseResult.

Enumerator
rtNORMAL	Normal response.
rtDEFERRED	Defer response while waiting for an event – an error if deferred response not supported under current conditions.
rtHANDLED	Response already sent so request is handled, use if error was sent.
rtCLOSE	Close connection.

Constructor & Destructor Documentation

◆ MemcachedServerHandlerBase()

MemcachedServerHandlerBase ( )

inline

Constructor.

Member Function Documentation

◆ get_max_initial_read()

static size_t get_max_initial_read ( )

inlinestatic

◆ on_command()

virtual bool on_command	(	bool &	handled,
		SubString &	command_str,
		SubString &	params
	)

inlinevirtual

Called on any other command.

Use send_reply() or send_error() for response

Parameters

handled	Set to true if command handled, otherwise an error response is sent (unknown command)
command_str	Command string to use
params	Parameters string received, usually space delimited

Returns: Whether successful, false to close connection

◆ on_delete()

virtual DeleteResult on_delete	(	DeferredContext &	context,
		const SubString &	key
	)

inlinevirtual

Called on DELETE request to delete key and value.

On error call send_error() then return rtHANDLED or rtCLOSE

Parameters

context	Context for creating DeferredReply for deferred response
key	Key to delete

Returns

Delete result:

grOK if deleted successfully
drNOT_FOUND if key not found
rtDEFERRED for deferred response (i.e. must wait for another event)
- Not valid when 'noreply' flag is set (meaning the client doesn't want a reply)
- When deferred, an event using DeferredReply must be created and the event must call:
  - DeferredReply::deferred_reply_delete() to send the deferred response
  - or DeferredReply::deferred_reply_error() to finish with an error
rtHANDLED if response already sent – use if error was sent
rtCLOSE to stop this request and immediately close connection

◆ on_error()

virtual void on_error ( AsyncError err )

inlinevirtual

Called on error.

Parameters

err	Error code – see AsyncError

◆ on_flush_all()

virtual void on_flush_all ( ulong delay_sec )

inlinevirtual

Called on FLUSH_ALL request to expire all keys.

Parameters

delay_sec Number of seconds to delay the flush, 0 for immediate

◆ on_get()

virtual ResponseType on_get	(	DeferredContext &	context,
		const SubString &	key,
		GetAdvParams *	adv_params
	)

inlinevirtual

Called for each key in GET request.

GET request variants:
- GET is the normal request to get a value – below are advanced variants that add additional functionality
- GAT (get and update) to get and update expiration time at the same time – these requests are rejected unless enable_gat=true
- GETS (get for Compare-And-Swap) to get and return a cas_id for atomic Compare And Swap – these requests are rejected unless enable_cas=true
- GATS (get for Compare-And-Swap and update) combines both above variants – these requests are rejected unless enable_gat=true and enable_cas=true
Call send_value() to send a value for key – skip if key not found
This is called multiple times if a GET request has multiple keys
This is only called if on_get_start() returned grCONTINUE for this request
If any part of this response is deferred then this or on_get_start() or on_get_end() must return rtDEFERRED to indiciate this, otherwise results are undefined

Parameters

context	Context for creating DeferredReply for deferred response
key	Requested key to get
adv_params	Pointer to advanced params, NULL for normal GET request, non-null if this is an advanced GET variant request (see above)

Returns

Response result:

rtNORMAL to continue to next event
rtDEFERRED to continue, but also mark the response as deferred (i.e. must wait for another event)
- When deferred, an event using DeferredReply must be created and the event must call:
  - DeferredReply::deferred_reply_get() to send value for key (skip if not found)
  - DeferredReply::deferred_reply_get_end() to finish the deferred response
  - or DeferredReply::deferred_reply_error() to finish with an error
- When on_get() is called multiple times for multiple keys, each call returning rtDEFERRED must have a matching DeferredReply to finish that deferred response
rtHANDLED if response already sent – use if error was sent
rtCLOSE to stop this request and immediately close connection

◆ on_get_end()

virtual ResponseType on_get_end ( DeferredContext & context )

inlinevirtual

Called at end of GET request.

This is called after on_get_start() and after the last on_get() call for this request, and gives an oppurtunity for cleanup
- This is not called if on_get_start() or on_get() returned rtHANDLED or rtCLOSE
This marks the end of the GET request inputs, but deferred responses for this request may still be pending – the request is not complete until all deferred responses for it are completed

Parameters

context Context for creating DeferredReply for deferred response

Returns

Response result:

rtNORMAL to complete the GET request – default if method not implemented
rtDEFERRED to mark the response as deferred (i.e. must wait for another event)
- When deferred, an event using DeferredReply must be created and the event must call:
  - DeferredReply::deferred_reply_get() for each additional value per key (skip for keys not found)
  - DeferredReply::deferred_reply_get_end() to finish the deferred response
  - or DeferredReply::deferred_reply_error() to finish with an error
rtHANDLED if response already sent – use if error was sent
rtCLOSE to stop this request and close connection

◆ on_get_start()

virtual GetStartResult on_get_start	(	DeferredContext &	context,
		const SubString &	keys,
		GetAdvParams *	adv_params
	)

inlinevirtual

Called at the beginning of a GET request with all requested keys.

GET request variants:
- GET is the normal request to get a value – below are advanced variants that add additional functionality
- GAT (get and update) to get and update expiration time at the same time – these requests are rejected unless enable_gat=true
- GETS (get for Compare-And-Swap) to get and return a cas_id for atomic Compare And Swap – these requests are rejected unless enable_cas=true
- GATS (get for Compare-And-Swap and update) combines both above variants – these requests are rejected unless enable_gat=true and enable_cas=true
This allows handling all keys at once as a batch (if desired) – by default this returns gsrCONTINUE if not overridden
- If desired, use StrTokWord() to tokenize keys on space character
Call send_value() to send a value per requested key – skip for keys not found
It's ok to call send_value() for some values then defer the rest by returning rtDEFERRED

Parameters

context	Context for creating DeferredReply for deferred response
keys	Requested keys (space separated)
adv_params	Pointer to advanced params, NULL for normal GET request, non-null if this is an advanced GET variant request (see above) This same pointer is also passed to `on_get()` events for this request

Returns

Get result:

gsrCONTINUE to continue to on_get() events for each key – default if not overridden
gsrSKIP to skip on_get() events – on_get_end() is still called
This indicates all requested keys were retrieved and send_value() was called as needed
rtDEFERRED to skip on_get() events and setup for deferred response – on_get_end() is still called
- This indicates that all requested values were sent (if any) and at least one is deferred
- When deferred, an event using DeferredReply must be created and the event must call:
  - DeferredReply::deferred_reply_get() for each value per key (skip for keys not found)
  - DeferredReply::deferred_reply_get_end() to finish the deferred response
  - or DeferredReply::deferred_reply_error() to finish with an error
rtHANDLED if response already sent – use if error was sent – on_get() and on_get_end() will not be called for this response
rtCLOSE to stop this request and immediately close connection

◆ on_increment()

virtual IncrementResult on_increment	(	DeferredContext &	context,
		const SubString &	key,
		uint64	count,
		bool	decrement
	)

inlinevirtual

Called on INCR or DECR request to increment or decrement a numeric value.

Decrementing below 0 should result in 0
On error call send_error() then return rtHANDLED or rtCLOSE
If value for key is not numeric then this should be considered an error

Parameters

context	Context for creating DeferredReply for deferred response
key	Key to increment or decrement
count	Count to increment or decrement
decrement	Whether to decrement instead of increment, false to increment, true to decrement

Returns

Result:

UInt64 value for new value after increment/decrement
Null UInt64 value if key not found
rtDEFERRED for deferred response (i.e. must wait for another event)
- Not valid when 'noreply' flag is set (meaning the client doesn't want a reply)
- When deferred, an event using DeferredReply must be created and the event must call:
  - DeferredReply::deferred_reply_increment() to send the deferred response
  - or DeferredReply::deferred_reply_error() to finish with an error
rtHANDLED if response already sent – use if error was sent
rtCLOSE to stop this request and immediately close connection

◆ on_stats()

virtual void on_stats ( SubString & params )

inlinevirtual

Called on STATS request for statistics.

Use send_reply() for response

Parameters

params Parameter string received

◆ on_store()

virtual StoreResult on_store	(	DeferredContext &	context,
		StoreParams &	params,
		SubString &	value,
		Command	command,
		uint64	cas_id
	)

inlinevirtual

Called on STORE request to store a value.

How to store depends on the exact command:
- cSET: Store new value, replace if already exists
- cAPPEND: Store value, append to existing value, or set new value if doesn't exist
- cPREPEND: Store value, prepend to existing value, or set new value if doesn't exist
- cADD: Store new value, only if key doesn't already exist
- cREPLACE: Store new value, only if key already exists
- cCAS: Store with atomic swap operation, fails if item was modified since it was last retrieved – not enabled unless enable_cas=true
On error call send_error() then return rtHANDLED or rtCLOSE
If the store command is not supported do this:
send_error("Not implemented");
return rtHANDLED;

Parameters

context	Context for creating DeferredReply for deferred response
params	Storage parameters to use
value	Value to store
command	Exact store command used, one of: cSET, cAPPEND, cPREPEND, cADD, cREPLACE, cCAS cAPPEND and cPREPEND commands should only update values and ignore `params.flags` and `params.exptime`
cas_id	Compare And Swap ID from previous "gets" or "gats" command – positive for cCAS command, otherwise always 0

Returns

Store result:

Memcached::srSTORED if value successfully stored, or if 'noreply' flag is set
Memcached::srNOT_STORED if not stored due to unmet condition (cADD, cREPLACE, cAPPEND, cPREPEND)
- cADD: Used when key already exists (can't add new key)
- cREPLACE: Used when key doesn't already exist (nothing to replace)
- cAPPEND/cPREPEND: Used when key doesn't already exist (nothing to append/prepend)
CAS:
- Memcached::srEXISTS if Compare And Swap failed due to value being modified since last retrieved with cas_id (cCAS only)
- Memcached::srNOT_FOUND if Compare And Swap failed due to value not existing (cCAS only)
rtDEFERRED for deferred response (i.e. must wait for another event)
- Not valid when 'noreply' flag is set (meaning the client doesn't want a reply)
- When deferred, an event using DeferredReply must be created and the event must call:
  - DeferredReply::deferred_reply_store() to send the deferred response
  - or DeferredReply::deferred_reply_error() to finish with an error
rtHANDLED if response already sent – use if error was sent
rtCLOSE to stop this request and immediately close connection

◆ on_touch()

virtual TouchResult on_touch	(	DeferredContext &	context,
		const SubString &	key,
		int64	expire
	)

inlinevirtual

Called on TOUCH request to update expiration of existing key without retrieving the value.

On error call send_error() then return rtHANDLED or rtCLOSE

Parameters

context	Context for creating DeferredReply for deferred response
key	Key to delete
expire	New expiration time in seconds from now, 0 for no expiration, negative to expire now, or a value greater than 2592000 (30 days) means a Unix timestamp to expire on

Returns

Touch result:

grOK if successful
drNOT_FOUND if key not found
rtDEFERRED for deferred response (i.e. must wait for another event)
- Not valid when 'noreply' flag is set (meaning the client doesn't want a reply)
- When deferred, an event using DeferredReply must be created and the event must call:
  - DeferredReply::deferred_reply_touch() to send the deferred response
  - or DeferredReply::deferred_reply_error() to finish with an error
rtHANDLED if response already sent – use if error was sent
rtCLOSE to stop this request and immediately close connection

◆ on_version()

virtual void on_version ( String & version )

inlinevirtual

Called on VERSION request for server version.

Use send_reply() for response

Parameters

version Set to version string to return (no newline chars) [out]

◆ send_client_error()

void send_client_error ( const SubString & msg )

inline

Helper to send a client error response.

Parameters

msg	Error message to send

◆ send_error()

void send_error ( const SubString & msg )

inline

Helper to send a server error response.

Parameters

msg	Error message to send

◆ send_reply()

void send_reply ( const SubString & msg )

inline

Helper to send a reply message.

Parameters

msg	Reply message to send

◆ send_stat()

void send_stat	(	const SubString &	name,
		const SubString &	value
	)

inline

Helper for sending statistics.

Call from on_stats()
Call repeatedly for each statistic

Parameters

name	Stats name
value	Stats value

◆ send_value()

void send_value	(	const SubString &	key,
		const SubString &	value,
		uint32	flags = `0`,
		uint64 *	cas_id = `NULL`
	)

inline

Helper to send value for get response.

Call from on_get_start() or on_get() if key and value found

Parameters

key	Key for value
value	Value to send
flags	User defined flags stored with value
cas_id	Compare-And-Swap ID to send, NULL for none – this must only be non-null for CAS GET request variants, see GetAdvParams

◆ set_id()

void set_id ( )

inlineinherited

Create and set new ID for current request/response.

Called by parent protocol class

Member Data Documentation

◆ buffers

AsyncBuffers buffers

inherited

Buffers for async I/O.

◆ enable_cas

bool enable_cas

Derived constructor must set to true to enable "compare and swap" (gets/gats command)

◆ enable_gat

bool enable_gat

Derived constructor must set to true to enable "get and touch" (gat/gats command)

◆ id

ulong id

inherited

Request/reply ID, used by reply manager (set by parent protocol class)

◆ logger

LoggerPtr logger

Logger to use (set by AsyncServer)

◆ MAX_INITIAL_READ

const size_t MAX_INITIAL_READ = 8192

staticinherited

Max initial read size.

Default is 8 KB, but the protocol handler may override with a new default
Override to tune
Use 0 for unlimited (not recommended)

◆ noreply

bool noreply

Whether no-reply mode is enabled (set by parent protocol class)

◆ reply

AsyncServerReply reply

inherited

Server reply manager, used to track deferred events and queue out of order replies.

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

evo/async/memcached_server.h

Detailed Description

Classes

Public Types

Public Member Functions

Static Public Member Functions

Public Attributes

Static Public Attributes

Member Typedef Documentation

◆ DeferredContext

◆ DeleteResult

◆ GetStartResult

◆ IncrementResult

◆ Memcached

◆ StoreResult

◆ TouchResult

Member Enumeration Documentation

◆ Command

◆ GeneralResultValue

◆ GetStartResultValue

◆ ResponseType

Constructor & Destructor Documentation

◆ MemcachedServerHandlerBase()

Member Function Documentation

◆ get_max_initial_read()

◆ on_command()

◆ on_delete()

◆ on_error()

◆ on_flush_all()

◆ on_get()

◆ on_get_end()

◆ on_get_start()

◆ on_increment()

◆ on_stats()

◆ on_store()

◆ on_touch()

◆ on_version()

◆ send_client_error()

◆ send_error()

◆ send_reply()

◆ send_stat()

◆ send_value()

◆ set_id()

Member Data Documentation

◆ buffers

◆ enable_cas

◆ enable_gat

◆ id

◆ logger

◆ MAX_INITIAL_READ

◆ noreply

◆ reply