|
Couchbase C Client
3.3.15
Asynchronous C Client for Couchbase
|
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. | |
| lcb_STATUS lcb_pktfwd3 | ( | lcb_INSTANCE * | instance, |
| const void * | cookie, | ||
| const lcb_CMDPKTFWD * | cmd ) |
Forward a raw memcached packet to the cluster.
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:
header and extras fields. This means that commands like OBSERVE and GET_CLUSTER_CONFIG 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.
| 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. |
| 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.
| instance | the handle |
| callback | the callback to install |
callback is NULL, this function just returns the existing 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.
| instance | the handle |
| callback | the callback to install |
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.
| buf | the buffer which backs the IOV After the buffer has been unreferenced, the relating IOV may no longer be accessed |
| struct lcb_CMDPKTFWD |
| struct lcb_PKTFWDRESP |
| 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.
| 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()
| typedef void(* lcb_pktflushed_callback) (lcb_INSTANCE *instance, const void *cookie) |
Callback invoked when the request buffer for a packet is no longer required.
| instance | |
| cookie | The cookie associated with the request data |
1.13.2