Name

lcb_get_replica — Retrieve a document from a replica location in the cluster

Synopsis

cc [ flag … ] file… -lcouchbase [ library … ]

#include <libcouchbase/couchbase.h>
lcb_error_t lcb_get_replica(lcb_t instance,
                            const void *command_cookie,
                            lcb_size_t num,
                            const lcb_get_replica_cmd_t *const *commands);

DESCRIPTION

lcb_get_replica() is used to retrieve replica documents from the cluster. If the library instance is using asynchronous mode (the default) this operation will return immediately and schedule the operations to be executed by the event loop, otherwise it will block until all commands are executed. command_cookie is is an opaque field that will be provided to the callback function. num is the number of entries in the commands array.

lcb_get_replica_cmd_t is a structure defined in <libcouchbase/arguments.h>:

typedef struct lcb_get_replica_cmd_st {
    int version;              /* The enty in "v" to use */
    union {
        struct {
            const void *key;    /* The key this response belongs to */
            lcb_size_t nkey;    /* The number of bytes in the key */
            const void *hashkey; /* hash key if != key */
            lcb_size_t nhashkey; /* number of bytes in hash key */
        } v0;
        struct {
            const void *key;
            lcb_size_t nkey;
            const void *hashkey;
            lcb_size_t nhashkey;
            lcb_replica_t strategy; /* how to select replica node */
            int index;              /* the replica index in case
                                       LCB_REPLICA_SELECT strategy */
        } v1;
    } v;
} lcb_get_replica_cmd_t;

Upon completion the get callback as set by lcb_set_get_callback is called.

From command version 1, it is possible to select strategy of how to select the replica node. Currently three strategies are available:

  1. LCB_REPLICA_FIRST: Previously accessible and default as of 2.0.8, the caller will get a reply from the first replica to successfully reply within the timeout for the operation or will receive an error.
  2. LCB_REPLICA_ALL: Ask all replicas to send documents/items back.
  3. LCB_REPLICA_SELECT: Select one replica by the index in the configuration starting from zero. This approach can more quickly receive all possible replies for a given topology, but it can also generate false negatives.

Note that applications should not assume the order of the replicas indicates more recent data is at a lower index number. It is up to the application to determine which version of a document/item it may wish to use in the case of retrieving data from a replica.

RETURN VALUES

lcb_get_replica() returns the LCB_SUCCESS on success, or a specific error code upon failure. See lcb_strerror(3couchbase) for more information.

EXAMPLES

Example 1: Get document from the second replica

#include <libcouchbase/couchbase.h>
...
lcb_t instance;
...
lcb_get_replica_cmd_t *get = calloc(1, sizeof(*get));
get->version = 1;
get->v.v1.key = "my-key";
get->v.v1.nkey = strlen(get->v.v0.key);
get->v.v1.strategy = LCB_REPLICA_SELECT;
get->v.v1.index = 2;
lcb_get_replica_cmd_st* commands[] = { get };
lcb_get_replica(instance, NULL, 1, commands);
...

Example 2: Get document from the first available replica

#include <libcouchbase/couchbase.h>
...
lcb_t instance;
...
lcb_get_replica_cmd_t *get = calloc(1, sizeof(*get));
get->version = 1;
get->v.v1.key = "my-key";
get->v.v1.nkey = strlen(get->v.v0.key);
get->v.v1.strategy = LCB_REPLICA_FIRST;
lcb_get_replica_cmd_st* commands[] = { get };
lcb_get_replica(instance, NULL, 1, commands);
...

Example 3: Get document from all replicas (will generate lcb_get_num_replicas() responses)

#include <libcouchbase/couchbase.h>
...
lcb_t instance;
...
lcb_get_replica_cmd_t *get = calloc(1, sizeof(*get));
get->version = 1;
get->v.v1.key = "my-key";
get->v.v1.nkey = strlen(get->v.v0.key);
get->v.v1.strategy = LCB_REPLICA_ALL;
lcb_get_replica_cmd_st* commands[] = { get };
lcb_get_replica(instance, NULL, 1, commands);
...

Example 4: Simple get replica (API v0)

#include <libcouchbase/couchbase.h>
...
lcb_t instance;
...
lcb_get_replica_cmd_t *get = calloc(1, sizeof(*get));
get->version = 0;
get->v.v0.key = "my-key";
get->v.v0.nkey = strlen(get->v.v0.key);
lcb_get_replica_cmd_st* commands[] = { get };
lcb_get_replica(instance, NULL, 1, commands);
...

ATTRIBUTES

See lcb_attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE ATTRIBUTE VALUE

Interface Stability

Committed

MT-Level

MT-Safe

COPYRIGHT

Copyright 2010-2013 Couchbase, Inc.

SEE ALSO

Learn more at http://www.couchbase.com/communities/c.

libcouchbase(3lib), lcb_get_get_callback(3couchbase), lcb_set_get_callback(3couchbase), lcb_attributes(5)