Couchbase C Client  2.10.6
Asynchronous C Client for Couchbase
Read (Replica)

Detailed Description

Retrieve a document from a replica if it cannot be fetched from the primary.

Functions

lcb_error_t lcb_rget3 (lcb_t instance, const void *cookie, const lcb_CMDGETREPLICA *cmd)
 Spool a single get-with-replica request. More...
 

Enumerations

enum  lcb_replica_t
 Select get-replica mode. More...
 

Function Documentation

◆ lcb_rget3()

lcb_error_t lcb_rget3 ( lcb_t  instance,
const void *  cookie,
const lcb_CMDGETREPLICA cmd 
)

Spool a single get-with-replica request.

Stability
Committed:
Parameters
instance
cookie
cmd
Returns
LCB_SUCCESS on success, error code otherwise.

When a response is received, the callback installed for LCB_CALLBACK_GETREPLICA will be invoked. The response will be an lcb_RESPGET pointer.

### Request

lcb_CMDGETREPLICA cmd = { 0 };
LCB_CMD_SET_KEY(&cmd, "key", 3);
lcb_rget3(instance, cookie, &cmd);

### Response

static void rget_callback(lcb_t instance, int cbtype, const lcb_RESPBASE *rb)
{
const lcb_RESPGET *resp = (const lcb_RESPGET *)rb;
printf("Got Get-From-Replica response for %.*s\n", (int)resp->key, resp->nkey);
if (resp->rc == LCB_SUCCESS) {
printf("Got response: %.*s\n", (int)resp->value, resp->nvalue);
else {
printf("Couldn't retrieve: %s\n", lcb_strerror(NULL, resp->rc));
}
}
Warning
As this function queries a replica node for data it is possible that the returned document may not reflect the latest document in the server.
This function should only be used in cases where a normal lcb_get3() has failed, or where there is reason to believe it will fail. Because this function may query more than a single replica it may cause additional network and server-side CPU load. Use sparingly and only when necessary.

Data Structure Documentation

◆ lcb_CMDGETREPLICA

struct lcb_CMDGETREPLICA

Command for requesting an item from a replica.

Note
The options.exptime and options.cas fields are ignored for this command.

This structure is similar to lcb_RESPGET with the addition of an index and strategy field which allow you to control and select how many replicas are queried.

See also
lcb_rget3(), lcb_RESPGET
Data Fields
lcb_U32 cmdflags Common flags for the command.

These modify the command itself. Currently the lower 16 bits of this field are reserved, and the higher 16 bits are used for individual commands.

lcb_U32 exptime Specify the expiration time.

This is either an absolute Unix time stamp or a relative offset from now, in seconds. If the value of this number is greater than the value of thirty days in seconds, then it is a Unix timestamp. This field is used in mutation operations (lcb_store3()) to indicate the lifetime of the item. It is used in lcb_get3() with the lcb_CMDGET::lock option to indicate the lock expiration itself.

lcb_U64 cas The known CAS of the item.

This is passed to mutation to commands to ensure the item is only changed if the server-side CAS value matches the one specified here. For other operations (such as lcb_CMDENDURE) this is used to ensure that the item has been persisted/replicated to a number of servers with the value specified here.

lcb_KEYBUF key The key for the document itself.

This should be set via LCB_CMD_SET_KEY()

lcb_KEYBUF _hashkey
Stability
Volatile:
lcb_replica_t strategy Strategy for selecting a replica.

The default is LCB_REPLICA_FIRST which results in the client trying each replica in sequence until a successful reply is found, and returned in the callback.

LCB_REPLICA_FIRST evaluates to 0.

Other options include:

Note
When LCB_REPLICA_ALL is selected, the callback will be invoked multiple times, one for each replica. The final callback will have the LCB_RESP_F_FINAL bit set in the lcb_RESPBASE::rflags field. The final response will also contain the response from the last replica to respond.
int index Valid only when strategy is LCB_REPLICA_SELECT, specifies the replica index number to query.

This should be no more than nreplicas-1 where nreplicas is the number of replicas the bucket is configured with.

Enumeration Type Documentation

◆ lcb_replica_t

Select get-replica mode.

See also
lcb_rget3_cmd_t
Enumerator
LCB_REPLICA_FIRST 

Query all the replicas sequentially, retrieving the first successful response.

LCB_REPLICA_ALL 

Query all the replicas concurrently, retrieving all the responses.

LCB_REPLICA_SELECT 

Query the specific replica specified by the lcb_rget3_cmd_t::index field.