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

lcb_install_callback3(instance, LCB_CALLBACK_GETREPLICA, rget_callback);
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.

• LCB_KEY_ENOENT if the key is not found on the replica(s), LCB_NO_MATCHING_SERVER if there are no replicas (either configured or online), or if the given replica (if lcb_CMDGETREPLICA::strategy is LCB_REPLICA_SELECT) is not available or is offline.

---

Data Structure Documentation

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: LCB_REPLICA_ALL - queries all replicas concurrently and dispatches a callback for each reply LCB_REPLICA_SELECT - queries a specific replica indicated in the index field 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

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