User Cookies

Detailed Description

Associate user-defined data with operations

User-defined pointers may be passed to all operations in the form of a cookie parameter. This cookie parameter allows any kind of application context to be accessible via the callback (in lcb_RESPBASE::cookie).

The library will not inspect or manage the address or contents of the cookie; it may live on the stack (especially if using the library synchronously), on the heap, or may be NULL altogether.

In addition to per-operation cookies, the library allows the instance itself (i.e. the lcb_INSTANCE object) to contain its own cookie. This is helpful when there is a wrapper object which needs to be accessed from within the callback

Function Documentation

lcb_set_cookie()

void lcb_set_cookie	(	lcb_INSTANCE *	instance,
		const void *	cookie )

Associate a cookie with an instance of lcb.

The cookie is a user defined pointer which will remain attached to the specified lcb_INSTANCE for its duration. This is the way to associate user data with the lcb_INSTANCE.

Parameters

instance	the instance to associate the cookie to
cookie	the cookie to associate with this instance.

Attention

There is no destructor for the specified cookie stored with the instance; thus you must ensure to manually free resources to the pointer (if it was dynamically allocated) when it is no longer required.

Stability

Committed

typedef struct {
  const char *status;
  // ....
} instance_info;
 
static void bootstrap_callback(lcb_INSTANCE *instance, lcb_STATUS err) {
  instance_info *info = (instance_info *)lcb_get_cookie(instance);
  if (err == LCB_SUCCESS) {
    info->status = "Connected";
  } else {
    info->status = "Error";
  }
}
 
static void do_create(void) {
  instance_info *info = calloc(1, sizeof(*info));
  // info->status is currently NULL
  // .. create the instance here
  lcb_set_cookie(instance, info);
  lcb_set_bootstrap_callback(instance, bootstrap_callback);
  lcb_connect(instance);
  lcb_wait(instance, LCB_WAIT_DEFAULT);
  printf("Status of instance is %s\n", info->status);
}

Examples

example/libeventdirect/main.c.

lcb_get_cookie()

const void * lcb_get_cookie

(

lcb_INSTANCE *

instance

)

Retrieve the cookie associated with this instance.

Parameters

instance

the instance of lcb

Returns

The cookie associated with this instance or NULL

See also

lcb_set_cookie()

Stability

Committed

Examples

example/libeventdirect/main.c.