Couchbase C Client  2.4.0
Raw packet forwarding and dispatch routines

Detailed Description

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

Functions

lcb_error_t lcb_pktfwd3 (lcb_t instance, const void *cookie, const lcb_CMDPKTFWD *cmd)
 Forward a raw memcached packet to the cluster.
lcb_pktfwd_callback lcb_set_pktfwd_callback (lcb_t instance, lcb_pktfwd_callback callback)
 Set the callback to be invoked when a response to a forwarded packet has been received.
lcb_pktflushed_callback lcb_set_pktflushed_callback (lcb_t 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.

Typedefs

typedef struct rdb_ROPESEG * lcb_BACKBUF
typedef void(* lcb_pktfwd_callback )(lcb_t instance, const void *cookie, lcb_error_t err, lcb_PKTFWDRESP *resp)
 Callback invoked when a response packet has arrived for a request.
typedef void(* lcb_pktflushed_callback )(lcb_t instance, const void *cookie)
 Callback invoked when the request buffer for a packet is no longer required.

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_error_t lcb_pktfwd3 ( lcb_t  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
instancethe handle
cookiea pointer to be passed to the callbacks for this packet
cmdthe command structure containing the buffer mappings for this packet.
Returns
LCB_SUCCESS on success, LCB_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_pktfwd_callback lcb_set_pktfwd_callback ( lcb_t  instance,
lcb_pktfwd_callback  callback 
)

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

Stability
Uncommitted:
Parameters
instancethe handle
callbackthe callback to install
Returns
the old callback. If callback is NULL, this function just returns the existing callback
lcb_pktflushed_callback lcb_set_pktflushed_callback ( lcb_t  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
instancethe handle
callbackthe callback to install
Returns
the old callback. If callback is NULL then this function just returns the existing callback.
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.

void lcb_backbuf_unref ( lcb_BACKBUF  buf)

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

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

Data Structure Documentation

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

typedef void(* lcb_pktfwd_callback)(lcb_t instance, const void *cookie, lcb_error_t err, lcb_PKTFWDRESP *resp)

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

Parameters
instance
cookieOpaque pointer associated with the request
errIf a response packet could not be obtained, this contains the reason
respResponse 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()

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

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

Parameters
instance
cookieThe cookie associated with the request data