Raw packet forwarding and dispatch routines

Detailed Description

These functions perform packet forwarding functions to send and receive raw packets

Response Buffer Handling
The data received as part of a response buffer is mapped by an lcb_IOV structure, however the actual allocated data is held together by an opaque lcb_BACKBUF structure. This structure allows multiple IOVs to exist concurrently within the same block of allocated memory (with different offsets and sizes). The lcb_BACKBUF structure functions as an opaque reference counted object which controls the duration of the memmory to which the IOV is mapped. From an API perspective, there is a one-to-one correlation between an IOV and an lcb_BACKBUF
void	lcb_backbuf_ref (lcb_BACKBUF buf)
	Indicate that the lcb_BACKBUF object which provides storage for an IOV's data pointer will need to remain valid until lcb_backbuf_unref() is called.
void	lcb_backbuf_unref (lcb_BACKBUF buf)
	Indicate that the IOV backed by the specified buf is no longer required.

Function Documentation

lcb_pktfwd3()

lcb_STATUS lcb_pktfwd3	(	lcb_INSTANCE *	instance,
		const void *	cookie,
		const lcb_CMDPKTFWD *	cmd )

Forward a raw memcached packet to the cluster.

Stability

Uncommitted

This function will process a buffer containing a raw complete memcached packet to the cluster. Once the reply for the packet has been received, the lcb_pktfwd_callback will be invoked with the cookie argument and the response data.

If using user-allocated buffers, an additional lcb_pktflushed_callback will be invoked once the library no longer needs the buffers for the packet. Note that no assumption should be made on the order of invocation for these two callbacks - thus it is recommended to implement a reference counting scheme on the buffer and decrement the count for each invocation of the callback.

Note that not all memcached commands may be forwarded to this function. Specifically, any packet passed to this function:

1. Must contain a single key after the header and extras fields. This means that commands like OBSERVE and GET_CLUSTER_CONFIG are not currently supported.
2. The key must be mappable via the vBucket mapping algorithm. This means that commands such as STATS are not currently supported.
3. Must receive exactly one reply from the server. This means that "quiet" versions of commands, such as GETQ and SETQ are not currently supported.

If you wish to forward one of the unsupported commands you may use the higher level entry points (i.e. lcb_stats3(), lcb_observe3_ctxnew(), etc) and manually reconstruct the output packet based on the callbacks received.

Note additionally that the opaque field within the packet will be modified by the library. You should store the current opaque value in the structure pointed to by the cookie parameter and then re-assign it once the packet callback has been delivered.

Forwarded packets are subject to the same lifecycle as normal commands. This means they may be retried and remapped to other nodes upon topology changes, and that they are subject to the same operation timeout semantics.

Parameters

instance	the handle
cookie	a pointer to be passed to the callbacks for this packet
cmd	the command structure containing the buffer mappings for this packet.

Returns

LCB_SUCCESS on success, LCB_ERR_INCOMPLETE_PACKET if the packet passed does not contain the full body. Other error codes may be returned as well

See also

lcb_set_pktfwd_callback lcb_set_pktflushed_callback, mc_forward_packet

lcb_set_pktfwd_callback()

lcb_pktfwd_callback lcb_set_pktfwd_callback	(	lcb_INSTANCE *	instance,
		lcb_pktfwd_callback	callback )

Set the callback to be invoked when a response to a forwarded packet has been received.

Stability

Uncommitted

Parameters

instance	the handle
callback	the callback to install

Returns

the old callback. If callback is NULL, this function just returns the existing callback

lcb_set_pktflushed_callback()

lcb_pktflushed_callback lcb_set_pktflushed_callback	(	lcb_INSTANCE *	instance,
		lcb_pktflushed_callback	callback )

Set the callback to be invoked when the buffer data supplied to the packet forwarding function is no longer needed.

Stability

Uncommitted

Parameters

instance	the handle
callback	the callback to install

Returns

the old callback. If callback is NULL then this function just returns the existing callback.

lcb_backbuf_ref()

void lcb_backbuf_ref

(

lcb_BACKBUF

buf

)

Indicate that the lcb_BACKBUF object which provides storage for an IOV's data pointer will need to remain valid until lcb_backbuf_unref() is called.

This function may be called from an lcb_pktfwd_callback handler to allow the contents of the buffer to persist outside the specific callback invocation.

lcb_backbuf_unref()

void lcb_backbuf_unref

(

lcb_BACKBUF

buf

)

Indicate that the IOV backed by the specified buf is no longer required.

Parameters

buf	the buffer which backs the IOV After the buffer has been unreferenced, the relating IOV may no longer be accessed

---

Data Structure Documentation

lcb_CMDPKTFWD

struct lcb_CMDPKTFWD

Request for forwarding a packet This structure is passed to the lcb_pktfwd3() function.

Data Fields
int	version
lcb_VALBUF	vb	This structure should be initialized to a packet. The packet may be in the form of a contiguous buffer to be copied (lcb_VALBUF::vtype should be LCB_KV_COPY), a contiguous buffer to be maintained by the user (lcb_VALBUF::vtype should be LCB_KV_CONTIG) or an array of lcb_IOV structures (which should not be copied; lcb_VALBUF::vtype should be LCB_KV_IOV). This field must contain a complete packet including any extras and body associated with it. If the buffer(s) passed are not copied, you must wait for the lcb_pktflushed_callback to be invoked to signal that the buffer is no longer needed and may be released back to the application. Warning The first 24 bytes of the buffer (i.e. the memcached header) will be modified. Currently this is used to modify the opaque field within the header.
char	nomap	Whether to direct this command to a specific server. This should be set if the packet itself doesn't contain any mapping information; and should not be used on normal key access commands, since key access commands should be mapped to the appropriate server via the vbucket mappet. The server should be specified in the server_index field
lcb_U16	server_index	Specify server index for the command. Only valid if nomap is specified.

lcb_PKTFWDRESP

struct lcb_PKTFWDRESP

Response structure containing the response for a packet.

Data Fields
int	version	Version of the response structure.
const lcb_U8 *	header	Pointer to the memcached header. This pointer is guaranteed to be properly aligned as a protocol_binary_response_header structure and will typically be quicker to access than analyzing the header as found inside the iovs field. This field may be NULL if the callback is invoked with an error.
lcb_IOV *	iovs	Array of lcb_IOV structures containing the response packet. The number of items in this array is contained in the nitems field. Note that you may modify the contents of the buffers themselves (i.e. the memory pointed to by lcb_IOV::iov_base. When a buffer is no longer needed, lcb_backbuf_unref() should be called on its associated lcb_BACKBUF structure - which is located at the same array index within the bufs field (for example, iovs[n] will have its associated lcb_BACKBUF structure at bufs[n].
lcb_BACKBUF *	bufs	Contains the backing lcb_BACKBUF objects which control the allocation lifespan of their associated elements in the iovs field.
unsigned	nitems	The number of items in the iovs and bufs array. Currently this is always 1 but may change in the future.

Typedef Documentation

lcb_pktfwd_callback

typedef void(* lcb_pktfwd_callback) (lcb_INSTANCE *instance, const void *cookie, lcb_STATUS err, lcb_PKTFWDRESP *resp)

Callback invoked when a response packet has arrived for a request.

Parameters

instance
cookie	Opaque pointer associated with the request
err	If a response packet could not be obtained, this contains the reason
resp	Response structure. This is always present if there is a reply from the server.

The lcb_PKTFWDRESP::bufs structures are considered to be invalid after the callback has exited because lcb_backbuf_unref() will be called on each of them. To ensure they remain valid in your application outside the callback, invoke lcb_backbuf_ref() on the required lcb_BACKBUF structures and then once they are no longer needed use lcb_backbuf_unref()

lcb_pktflushed_callback

typedef void(* lcb_pktflushed_callback) (lcb_INSTANCE *instance, const void *cookie)

Callback invoked when the request buffer for a packet is no longer required.

Parameters

instance
cookie	The cookie associated with the request data