Couchbase C Client  2.4.3
Ensure a key is replicated to a set of nodes

Detailed Description

The lcb_durability_poll() is used to wait asynchronously until the item have been persisted and/or replicated to at least the number of nodes specified in the durability options.

The command is implemented by sending a series of OBSERVE broadcasts (see lcb_observe()) to all the nodes in the cluster which are either master or replica for a specific key. It polls repeatedly until either the timeout interval has elapsed or all the items have been persisted and/or replicated to the number of nodes specified in the criteria.

Unlike most other API calls which accept only a per-key structure, the lcb_durability_opts_st (lcb_DURABILITYOPTSv0) structure affects the way the command will poll for all keys as a whole:

The lcb_DURABILITYOPTSv0::timeout field indicates the upper limit (in microseconds) of time the command will wait until all the keys' durability requirements are satisfied. If the durability requirements ae not satisfied when the timeout is reached, the outstanding keys will be set to an error status in the callback (see lcb_DURABILITYRESPv0::err). If set to 0, it will default to the value of the LCB_CNTL_DURABILITY_TIMEOUT setting.

The lcb_DURABILITYOPTSv0::interval field specifies how long to wait between each attempt at verifying the completion of the durability requirements. If not specified, this will be LCB_CNTL_DURABILITY_INTERVAL

The lcb_DURABILITYOPTSv0::persist_to field specifies how many nodes must contain the item on their disk in order for the command to succeed. The maximum value should be the number of nodes in the cluster.

The lcb_DURABILITYOPTSv0::replicate_to field specifies how many replicas must contain the item in their memory for this command to succeed. The maximum value should be the the number of replicas in the cluster.

The lcb_DURABILITYOPTSv0::check_delete flag indicates that this operation should check for the non-presence of an item. This is used to ensure a successful removal of an item via lcb_remove(). In this case, the semantics of 'persist_to' and 'replicate_to' are inverted, where 'persist_to' means the number of nodes where the item is deleted from the disk, and 'replicate_to' means the number of nodes where the item not present in the cache.

In all cases, the value of 'replicate_to' will implicitly always be at least the value of 'persist_to'-1.

The lcb_DURABILITYOPTSv0::cap_max field indicates that the library should set persist_to and replicate_to to their maximum available number if those fields are set beyond current limits. This will be set based on the number of nodes active in the cluster and the number of replicas the cluster is configured with.

Functions

lcb_error_t lcb_durability_poll (lcb_t instance, const void *cookie, const lcb_durability_opts_t *options, lcb_SIZE ncmds, const lcb_durability_cmd_t *const *cmds)
 Schedule a durability check on a set of keys. More...
 
lcb_durability_callback lcb_set_durability_callback (lcb_t, lcb_durability_callback)
 

Typedefs

typedef void(* lcb_durability_callback )(lcb_t instance, const void *cookie, lcb_error_t err, const lcb_durability_resp_t *res)
 Callback for durability status. More...
 

Function Documentation

lcb_error_t lcb_durability_poll ( lcb_t  instance,
const void *  cookie,
const lcb_durability_opts_t options,
lcb_SIZE  ncmds,
const lcb_durability_cmd_t *const *  cmds 
)

Schedule a durability check on a set of keys.

This callback wraps (somewhat) the lower-level OBSERVE (lcb_observe) operations so that users may check if a key is endured, e.g. if a key is persisted accross "at least" n number of servers

When each key has its criteria satisfied, the durability callback (see above) is invoked for it.

The callback may also be invoked when a condition is encountered that will prevent the key from ever satisfying the criteria.

Parameters
instancethe lcb handle
cookiea pointer to be received with each callback
optionsa set of options and criteria for this durability check
cmdsa list of key specifications to check for
ncmdshow many key specifications reside in the list
Returns
a status code showing whether the request was scheduled. If the request could not be scheduled, an error will be returned. Custom errors returned include LCB_DURABILITY_ETOOMANY which indicates that the number of servers specified by the user exceeds the possible number of servers that the key may be replicated and/or persisted to:

Example (after receiving a store callback)

lcb_durability_cmd_t cmd, cmds[1];
memset(&opts, 0, sizeof(opts);
memset(&cmd, 0, sizeof(cmd);
cmds[0] = &cmd;
opts.persist_to = 2;
opts.replicate_to = 1;
cmd.v.v0.key = resp->v.v0.key;
cmd.v.v0.nkey = resp->v.v0.nkey;
cmd.v.v0.cas = resp->v.v0.cas;
//schedule the command --
err = lcb_durability_poll(instance, cookie, &opts, &cmds, 1);
// error checking omitted --
// later on, in the callback. resp is now a durability_resp_t* --
if (resp->v.v0.err == LCB_SUCCESS) {
printf("Key was endured!\n");
} else {
printf("Key did not endure in time\n");
printf("Replicated to: %u replica nodes\n", resp->v.v0.nreplicated);
printf("Persisted to: %u total nodes\n", resp->v.v0.npersisted);
printf("Did we persist to master? %u\n",
resp->v.v0.persisted_master);
printf("Does the key exist in the master's cache? %u\n",
resp->v.v0.exists_master);
switch (resp->v.v0.err) {
printf("Seems like someone modified the key already...\n");
break;
printf("Either key does not exist, or the servers are too slow\n");
printf("If persisted_master or exists_master is true, then the"
"server is simply slow.",
"otherwise, the key does not exist\n");
break;
default:
printf("Got other error. This is probably a network error\n");
break;
}
}
Stability
Committed:

Data Structure Documentation

struct lcb_DURABILITYCMDv0

Single-key command structure for lcb_durability_poll()

Data Fields

const void * key
 
size_t nkey
 
struct lcb_durability_cmd_t
Data Fields
int version
union lcb_durability_cmd_t v
struct lcb_DURABILITYOPTSv0
Data Fields
lcb_U32 timeout Upper limit in microseconds from the scheduling of the command.

When this timeout occurs, all remaining non-verified keys will have their callbacks invoked with LCB_ETIMEDOUT

lcb_U32 interval The durability check may involve more than a single call to observe - or more than a single packet sent to a server to check the key status.

This value determines the time to wait between multiple probes for the same server. If left at 0, a sensible adaptive value will be used.

lcb_U16 persist_to how many nodes the key should be persisted to (including master)
lcb_U16 replicate_to how many nodes the key should be replicated to (excluding master)
lcb_U8 check_delete this flag inverts the sense of the durability check and ensures that the key does not exist
lcb_U8 cap_max If replication/persistence requirements are excessive, cap to the maximum available.
struct lcb_durability_opts_t

Options for lcb_durability_poll() (wrapper)

See also
lcb_DURABILITYOPTSv0
Data Fields
int version
union lcb_durability_opts_t v
struct lcb_DURABILITYRESPv0

Response structure for lcb_durability_poll()

Data Fields
const void * key
lcb_SIZE nkey
lcb_error_t err if this entry failed, this contains the reason, e.g.
  • LCB_KEY_EEXISTS: The key exists with a different CAS than expected
  • LCB_KEY_ENOENT: The key was not found in the master cache
  • LCB_ETIMEDOUT: The key may exist, but the required servers needed took too long to respond
lcb_cas_t cas if found with a different CAS, this is the CAS
unsigned char persisted_master Whether the key was persisted to the master.

For deletes, this means the key was removed from disk

unsigned char exists_master Whether the key exists on the master.

For deletes, this means the key does not exist in cache

unsigned char npersisted how many nodes (including master) this item was persisted to
unsigned char nreplicated how many nodes (excluding master) this item was replicated to
unsigned short nresponses Total number of observe responses received for the node.

This can be used as a performance metric to determine how many total OBSERVE probes were sent until this key was 'done'

Typedef Documentation

typedef void(* lcb_durability_callback)(lcb_t instance, const void *cookie, lcb_error_t err, const lcb_durability_resp_t *res)

Callback for durability status.

The callback is invoked on completion of each key (i.e. only one callback is invoked per-key).

Parameters
lcb_tthe instance
cookiethe user cookie
erran error
resa response containing information about the key.