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

instance	the lcb handle
cookie	a pointer to be received with each callback
options	a set of options and criteria for this durability check
cmds	a list of key specifications to check for
ncmds	how 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];
lcb_durability_opts_t opts;
lcb_error_t err;
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) {
     case LCB_KEY_EEXISTS:
         printf("Seems like someone modified the key already...\n");
         break;
     case LCB_ETIMEDOUT:
         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

lcb_durability_poll() Command wrapper

See also: lcb_DURABILITYCMDv0

Data Fields
int	version
union lcb_durability_cmd_t	v

struct lcb_DURABILITYOPTSv0

Options for lcb_durability_poll()

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 (in microseconds) between multiple probes for the same server. If left at 0, the LCB_CNTL_DURABILITY_INTERVAL will be used instead.
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_t	the instance
cookie	the user cookie
err	an error
res	a response containing information about the key.

Detailed Description

Functions

Typedefs

Function Documentation

Data Structure Documentation

Data Fields

Typedef Documentation