Get items from the cluster

Detailed Description

Get one or more keys from the cluster.

Included in these functions are means by which to temporarily lock access to an item, modify its expiration, and retrieve an item from a replica.

Functions
lcb_get_callback	lcb_set_get_callback (lcb_t, lcb_get_callback callback)
	Set the callback to be invoked when an item is received as a result of an lcb_get() operation. More...
lcb_error_t	lcb_get (lcb_t instance, const void *command_cookie, lcb_SIZE num, const lcb_get_cmd_t *const *commands)
	Get a number of values from the cache. More...

Macros
#define	LCB_DATATYPE_JSON
	Value is JSON.

Typedefs
typedef void(*	lcb_get_callback )(lcb_t instance, const void *cookie, lcb_error_t error, const lcb_get_resp_t *resp)
	The callback function for a "get-style" request. More...

Enumerations
enum	lcb_VALUEFLAGS
	Flags which can be returned int the the lcb_GETRESPv0::datatype field. More...

Function Documentation

lcb_get_callback lcb_set_get_callback	(	lcb_t	,
		lcb_get_callback	callback
	)

Set the callback to be invoked when an item is received as a result of an lcb_get() operation.

Parameters

callback

the new callback to install. Pass NULL to only query the current callback

Returns

the previous callback

See also

lcb_get()

Stability

Committed:

Examples:

example/libeventdirect/main.c, and example/minimal/minimal.c.

lcb_error_t lcb_get	(	lcb_t	instance,
		const void *	command_cookie,
		lcb_SIZE	num,
		const lcb_get_cmd_t *const *	commands
	)

Get a number of values from the cache.

If you specify a non-zero value for expiration, the server will update the expiration value on the item (refer to the documentation on lcb_store to see the meaning of the expiration). All other members should be set to zero.

lcb_get_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);
// Set an expiration of 60 (optional)
get->v.v0.exptime = 60;
lcb_get_cmd_t* commands[] = { get };
lcb_get(instance, NULL, 1, commands);

It is possible to get an item with a lock that has a timeout. It can then be unlocked with either a CAS operation or with an explicit unlock command.

You may specify the expiration value for the lock in the expiration (setting it to 0 cause the server to use the default value).

Get and lock the key:

lcb_get_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);
// Set a lock expiration of 5 (optional)
get->v.v0.lock = 1;
get->v.v0.exptime = 5;
lcb_get_cmd_t* commands[] = { get };
lcb_get(instance, NULL, 1, commands);

Parameters

instance	the instance used to batch the requests from
command_cookie	A cookie passed to all of the notifications from this command
num	the total number of elements in the commands array
commands	the array containing the items to get

Returns

The status of the operation

Stability

Committed:

Examples:

example/libeventdirect/main.c, and example/minimal/minimal.c.

---

Data Structure Documentation

struct lcb_GETCMDv0

Get Command Structure.

Data Fields
const void *	key	Key to retrieve.
lcb_SIZE	nkey	Key length.
lcb_time_t	exptime	If this parameter is specified and lock is not set then the server will also update the object's expiration time while retrieving the key. If lock is set then this is the maximum amount of time the lock may be held (before an unlock) before the server will forecfully unlock the key.
int	lock	If this parameter is set then the server will in addition to retrieving the item also lock the item, making it so that subsequent attempts to lock and/or modify the same item will fail with an error (either LCB_KEY_EEXISTS or LCB_ETMPFAIL). The lock will be released when one of the following happens: The item is explicitly unlocked (see lcb_unlock()) The lock expires (See the exptime parameter) The item is modified using lcb_store(), and being provided with the correct CAS.

struct lcb_get_cmd_t

lcb_get() Command Wrapper Structure

See also

lcb_GETCMDv0

Examples:

example/libeventdirect/main.c, and example/minimal/minimal.c.

Data Fields
int	version
union lcb_get_cmd_t	v

struct lcb_GETRESPv0

Inner response structure for a get operation.

Data Fields
const void *	key
lcb_SIZE	nkey
const void *	bytes
lcb_SIZE	nbytes
lcb_U32	flags	Server side flags stored with the item.
lcb_cas_t	cas	CAS representing current mutation state of the item.
lcb_U8	datatype	Currently unused.

struct lcb_get_resp_t

lcb_get() response wrapper structure

See also

lcb_GETRESPv0

Examples:

example/libeventdirect/main.c, and example/minimal/minimal.c.

Data Fields
int	version
union lcb_get_resp_t	v

Typedef Documentation

typedef void(* lcb_get_callback)(lcb_t instance, const void *cookie, lcb_error_t error, const lcb_get_resp_t *resp)

The callback function for a "get-style" request.

Parameters

instance	the instance performing the operation
cookie	the cookie associated with with the command
error	The status of the operation
resp	More information about the actual item (only key and nkey is valid if error != LCB_SUCCESS)

Stability

Committed:

Enumeration Type Documentation

enum lcb_VALUEFLAGS

Flags which can be returned int the the lcb_GETRESPv0::datatype field.

Enumerator
LCB_VALUE_RAW	Value is raw bytes.
LCB_VALUE_F_JSON	Value is JSON.
LCB_VALUE_F_SNAPPYCOMP	Value is compressed as Snappy.