Read (Replica)

Detailed Description

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

Functions
lcb_STATUS	lcb_respgetreplica_status (const lcb_RESPGETREPLICA *resp)
int	lcb_respgetreplica_is_active (const lcb_RESPGETREPLICA *resp)
lcb_STATUS	lcb_respgetreplica_error_context (const lcb_RESPGETREPLICA *resp, const lcb_KEY_VALUE_ERROR_CONTEXT **ctx)
lcb_STATUS	lcb_respgetreplica_cookie (const lcb_RESPGETREPLICA *resp, void **cookie)
lcb_STATUS	lcb_respgetreplica_cas (const lcb_RESPGETREPLICA *resp, uint64_t *cas)
lcb_STATUS	lcb_respgetreplica_datatype (const lcb_RESPGETREPLICA *resp, uint8_t *datatype)
lcb_STATUS	lcb_respgetreplica_flags (const lcb_RESPGETREPLICA *resp, uint32_t *flags)
lcb_STATUS	lcb_respgetreplica_key (const lcb_RESPGETREPLICA *resp, const char **key, size_t *key_len)
lcb_STATUS	lcb_respgetreplica_value (const lcb_RESPGETREPLICA *resp, const char **value, size_t *value_len)
int	lcb_respgetreplica_is_final (const lcb_RESPGETREPLICA *resp)
lcb_STATUS	lcb_cmdgetreplica_create (lcb_CMDGETREPLICA **cmd, lcb_REPLICA_MODE mode)
lcb_STATUS	lcb_cmdgetreplica_destroy (lcb_CMDGETREPLICA *cmd)
lcb_STATUS	lcb_cmdgetreplica_parent_span (lcb_CMDGETREPLICA *cmd, lcbtrace_SPAN *span)
lcb_STATUS	lcb_cmdgetreplica_collection (lcb_CMDGETREPLICA *cmd, const char *scope, size_t scope_len, const char *collection, size_t collection_len)
lcb_STATUS	lcb_cmdgetreplica_key (lcb_CMDGETREPLICA *cmd, const char *key, size_t key_len)
lcb_STATUS	lcb_cmdgetreplica_timeout (lcb_CMDGETREPLICA *cmd, uint32_t timeout)
lcb_STATUS	lcb_cmdgetreplica_on_behalf_of (lcb_CMDGETREPLICA *cmd, const char *data, size_t data_len)
lcb_STATUS	lcb_cmdgetreplica_on_behalf_of_extra_privilege (lcb_CMDGETREPLICA *cmd, const char *privilege, size_t privilege_len)
lcb_STATUS	lcb_getreplica (lcb_INSTANCE *instance, void *cookie, const lcb_CMDGETREPLICA *cmd)

Typedefs
typedef struct lcb_RESPGETREPLICA_	lcb_RESPGETREPLICA
typedef struct lcb_CMDGETREPLICA_	lcb_CMDGETREPLICA

Enumerations
enum	lcb_REPLICA_MODE
	Spool a single get-with-replica request. More...

Function Documentation

lcb_cmdgetreplica_on_behalf_of()

lcb_STATUS lcb_cmdgetreplica_on_behalf_of	(	lcb_CMDGETREPLICA *	cmd,
		const char *	data,
		size_t	data_len
	)

Stability

Internal:

Internal: This should never be used and is not supported.

lcb_cmdgetreplica_on_behalf_of_extra_privilege()

lcb_STATUS lcb_cmdgetreplica_on_behalf_of_extra_privilege	(	lcb_CMDGETREPLICA *	cmd,
		const char *	privilege,
		size_t	privilege_len
	)

Stability

Internal:

Internal: This should never be used and is not supported.

Enumeration Type Documentation

lcb_REPLICA_MODE

enum lcb_REPLICA_MODE

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;
lcb_cmdgetreplica_create(&cmd);
lcb_cmdgetreplica_key(cmd, "key", 3);
lcb_cmdgetreplica(instance, cookie, &cmd);

Response

lcb_install_callback(instance, LCB_CALLBACK_GETREPLICA, rget_callback);
static void rget_callback(lcb_INSTANCE *instance, int cbtype, const lcb_RESPBASE *rb)
{
    const lcb_RESPGET *resp = (const lcb_RESPGET *)rb;
    char* key;
    char* value;
    size_t key_len;
    size_t value_len;
    lcb_STATUS rc = lcb_respgetreplica_status(resp);
    lcb_respgetreplica_key(resp, &key, &key_len);
    printf("Got Get-From-Replica response for %.*s\n", key_len, key);
    if (rc == LCB_SUCCESS) {
        lcb_respgetreplica_value(resp, &value, &value_len);
        printf("Got response: %.*s\n", value_len, value);
    else {
        printf("Couldn't retrieve: %s\n", lcb_strerror_short(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_ERR_DOCUMENT_NOT_FOUND if the key is not found on the replica(s), ::LCB_ERR_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.