Legacy Key-Value API

Detailed Description

Operate on one or more key values.

The key-value APIs are high performance APIs utilizing the memcached protocol. Use these APIs to access data by its unique key.

These APIs are designed so that each function is passed in one or more "Command Structures". A command structure is a small structure detailing a specific key and contains options and modifiers for the operation as it relates to that key.

All the command structures are currently layed out like so:

{
  int version;
  union {
    struct CMDv0 v0;
    struct CMDv1 v1;
  } v;
}

These top level structures are wrapper structures and are present to ensure portability between different versions of the library. To employ these structures within the command, you may do:

lcb_get_cmd_t gcmd_wrap = { 0 }, *cmdp_wrap = &gcmd_wrap;
lcb_GETCMDv0 *gcmd = &gcmd_wrap->v.v0;
gcmd->key = key;
gcmd->nkey = strlen(key);
lcb_get(instance, cookie, 1, &gcmd_wrap);

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...

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...

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:

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

Status code indicating whether the operation was scheduled or not. See 'exceptions' section for errors received in callbacks

Operation-specific errors received in callbacks include:

• LCB_KEY_ENOENT if the key does not exist
• LCB_ETMPFAIL if the lock option was set in the command and the item was already locked.

Stability

Committed:

---

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

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.

struct lcb_get_resp_t

lcb_get() response wrapper structure

See also

lcb_GETRESPv0

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: