Couchbase C Client  2.4.1
Basic Library Routines

Detailed Description

To communicate with a Couchbase cluster, a new library handle instance is created in the form of an lcb_t. To create such an object, the lcb_create() function is called, passing it a structure of type lcb_create_st. The structure acts as a container for a union of other structures which are extended as more features are added. This container is forwards and backwards compatible, meaning that if the structure is extended, you code and application will still function if using an older version of the structure. The current sub-field of the lcb_create_st structure is the v3 field.

Connecting to the cluster involes the client knowing the necessary information needed to actually locate its services and connect to it.

A connection specification consists of:

  1. One or more hosts which comprise the cluster
  2. The name of the bucket to access and perform operations on
  3. The credentials of the bucket

All these options are specified within the form of a URI in the form of

couchbase://$HOSTS/$BUCKET?$OPTIONS

Note
If any of the fields (hosts, bucket, options) contain the / character then it must be url-encoded; thus a bucket named foo/bar would be specified as couchbase:///foo%2Fbar

Hosts

In the most typical use case, you would specify a list of several hostnames delimited by a comma (,); each host specified should be a member of the cluster. The library will use this list to initially connect to the cluster.

Note that it is not necessary to specify all the nodes of the cluster as in a normal situation the library will only initially connect to one of the nodes. Passing multiple nodes increases the chance of a connection succeeding even if some of the nodes are currently down. Once connected to the cluster, the client will update itself with the other nodes actually found within the cluster and discard the list passed to it

You can specify multiple hosts like so:

couchbase://foo.com,bar.com,baz.com

Or a single host:

couchbase://localhost

Specifying Ports and Protocol Options

The default couchbase:// scheme will assume all hosts and/or ports specify the memcached port. If no port is specified, it is assumed that the port is _11210). For more extended options there are additional schemes available:

Bucket

A bucket may be specified by using the optional path component of the URI For protected buckets a password will still need to be supplied out of band.

Options

Warning
The key-value options here are considered to be a volatile interface as their names may change.

Options can be specified as the query part of the connection string, for example:

couchbase://cbnode.net/beer?operation_timeout=10000000.

Options may either be appropriate key parameters for lcb_cntl_string() or one of the following:

Bucket Identification and Credentials

The most common settings you will wish to modify are the bucket name and the credentials field (user and passwd). If a bucket is not specified it will revert to the default bucket (i.e. the bucket which is created when Couchbase Server is installed).

The user and passwd fields authenticate for the bucket. This is only needed if you have configured your bucket to employ SASL auth. You can tell if the bucket has been configured with SASL auth by

  1. Logging into the Couchbase Administration Console
  2. Going to the Data Buckets tab
  3. Locate the row for your bucket
  4. Expand the row into the detailed view (by clicking on the arrow at the left of the row)
  5. Click on Edit
  6. Inspect the Access Control section in the pop-up

The bucket name is specified as the path portion of the URI.

For security purposes, the user and passwd cannot be specified within the URI

Note
You may not change the bucket or credentials after initializing the handle.

Bootstrap Options

The default configuration process will attempt to bootstrap first from the new memcached configuration protocol (CCCP) and if that fails, use the "HTTP" protocol via the REST API.

The CCCP configuration will by default attempt to connect to one of the nodes specified on the port 11201. While normally the memcached port is determined by the configuration itself, this is not possible when the configuration has not been attained. You may specify a list of alternate memcached servers by using the 'mchosts' field.

If you wish to modify the default bootstrap protocol selection, you can use the bootstrap_on option to specify the desired bootstrap specification to use for configuration (note that the ordering of this array is ignored). Using this mechanism, you can disable CCCP or HTTP.

To force only "new-style" bootstrap, you may use bootstrap_on=cccp. To force only "old-style" bootstrap, use bootstrap_on=http. To force the default behavior, use bootstrap_on=all

Functions

lcb_error_t lcb_create (lcb_t *instance, const struct lcb_create_st *options)
 Create an instance of lcb. More...
 
lcb_error_t lcb_connect (lcb_t instance)
 Schedule the initial connection This function will schedule the initial connection for the handle. More...
 
void lcb_set_cookie (lcb_t instance, const void *cookie)
 Associate a cookie with an instance of lcb. More...
 
const void * lcb_get_cookie (lcb_t instance)
 Retrieve the cookie associated with this instance. More...
 
lcb_error_t lcb_wait (lcb_t instance)
 Wait for the execution of all batched requests. More...
 
void lcb_wait3 (lcb_t instance, lcb_WAITFLAGS flags)
 Wait for completion of scheduled operations. More...
 
void lcb_breakout (lcb_t instance)
 Forcefully break from the event loop. More...
 
lcb_bootstrap_callback lcb_set_bootstrap_callback (lcb_t instance, lcb_bootstrap_callback callback)
 Set the callback for notification of success or failure of initial connection. More...
 
lcb_error_t lcb_get_bootstrap_status (lcb_t instance)
 Gets the initial bootstrap status. More...
 
void lcb_refresh_config (lcb_t instance)
 Force the library to refetch the cluster configuration. More...
 
lcb_configuration_callback lcb_set_configuration_callback (lcb_t, lcb_configuration_callback)
 
void lcb_destroy (lcb_t instance)
 Destroy (and release all allocated resources) an instance of lcb. More...
 
lcb_destroy_callback lcb_set_destroy_callback (lcb_t, lcb_destroy_callback)
 Set the callback to be invoked when the instance is destroyed asynchronously. More...
 
void lcb_destroy_async (lcb_t instance, const void *arg)
 Asynchronously schedule the destruction of an instance. More...
 
lcb_error_t lcb_create_io_ops (lcb_io_opt_t *op, const struct lcb_create_io_ops_st *options)
 Create a new instance of one of the library-supplied io ops types. More...
 
lcb_error_t lcb_destroy_io_ops (lcb_io_opt_t op)
 Destory io ops instance. More...
 

Macros

#define LCB_IOCREATE_T_BUILTIN
 
#define LCB_IOCREATE_T_DSO
 
#define LCB_IOCREATE_T_FUNCTIONPOINTER
 

Typedefs

typedef void(* lcb_bootstrap_callback )(lcb_t instance, lcb_error_t err)
 Bootstrap callback. More...
 
typedef void(* lcb_configuration_callback )(lcb_t instance, lcb_configuration_t config)
 Receive notification upon cluster configuration. More...
 
typedef void(* lcb_destroy_callback )(const void *cookie)
 Callback received when instance is about to be destroyed. More...
 

Enumerations

enum  lcb_type_t
 Handle types. More...
 
enum  lcb_WAITFLAGS
 Flags for lcb_wait3() More...
 
enum  lcb_configuration_t
 Argument indicating configuration change type. More...
 
enum  lcb_io_ops_type_t
 Built-in I/O plugins. More...
 

Function Documentation

lcb_error_t lcb_create ( lcb_t *  instance,
const struct lcb_create_st options 
)

Create an instance of lcb.

Parameters
instanceWhere the instance should be returned
optionsHow to create the libcouchbase instance
Returns
LCB_SUCCESS on success

Examples

Create an instance using the default values:

lcb_t instance;
lcb_error_t err = lcb_create(&instance, NULL);
if (err != LCB_SUCCESS) {
fprintf(stderr, "Failed to create instance: %s\n", lcb_strerror(NULL, err));
exit(EXIT_FAILURE);
}

Specify server list

struct lcb_create_st options;
memset(&options, 0, sizeof(options));
options.version = 3;
options.v.v3.connstr = "couchbase://host1,host2,host3";
err = lcb_create(&instance, &options);

Create a handle for data requests to protected bucket

struct lcb_create_st options;
memset(&options, 0, sizeof(options));
options.version = 3;
options.v.v3.host = "couchbase://example.com,example.org/protected"
options.v.v3.passwd = "secret";
err = lcb_create(&instance, &options);
Stability
Committed:
See Also
lcb_create_st3
Examples:
example/libeventdirect/main.c, and example/minimal/minimal.c.
lcb_error_t lcb_connect ( lcb_t  instance)

Schedule the initial connection This function will schedule the initial connection for the handle.

This function must be called before any operations can be performed.

lcb_set_bootstrap_callback() or lcb_get_bootstrap_status() can be used to determine if the scheduled connection completed successfully.

lcb_wait() should be called after this function.

Stability
Committed:
Examples:
example/libeventdirect/main.c, and example/minimal/minimal.c.
void lcb_set_cookie ( lcb_t  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_t for its duration. This is the way to associate user data with the lcb_t.

Parameters
instancethe instance to associate the cookie to
cookiethe 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_t instance, lcb_error_t 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);
printf("Status of instance is %s\n", info->status);
}
Examples:
example/libeventdirect/main.c.
const void* lcb_get_cookie ( lcb_t  instance)

Retrieve the cookie associated with this instance.

Parameters
instancethe instance of lcb
Returns
The cookie associated with this instance or NULL
See Also
lcb_set_cookie()
Stability
Committed:
Examples:
example/libeventdirect/main.c.
lcb_error_t lcb_wait ( lcb_t  instance)

Wait for the execution of all batched requests.

A batched request is any request which requires network I/O. This includes most of the APIs. You should not use this API if you are integrating with an asynchronous event loop (i.e. one where your application code is invoked asynchronously via event loops).

This function will block the calling thread until either

  • All operations have been completed
  • lcb_breakout() is explicitly called
Parameters
instancethe instance containing the requests
Returns
whether the wait operation failed, or LCB_SUCCESS
Stability
Committed:
Examples:
example/minimal/minimal.c.
void lcb_wait3 ( lcb_t  instance,
lcb_WAITFLAGS  flags 
)

Wait for completion of scheduled operations.

Stability
Committed:
Parameters
instancethe instance
flagsflags to modify the behavior of lcb_wait(). Pass 0 to obtain behavior identical to lcb_wait().
void lcb_breakout ( lcb_t  instance)

Forcefully break from the event loop.

You may call this function from within any callback to signal to the library that it return control to the function calling lcb_wait() as soon as possible. Note that if there are pending functions which have not been processed, you are responsible for calling lcb_wait() a second time.

Parameters
instancethe instance to run the event loop for.
Stability
Committed:
lcb_bootstrap_callback lcb_set_bootstrap_callback ( lcb_t  instance,
lcb_bootstrap_callback  callback 
)

Set the callback for notification of success or failure of initial connection.

Parameters
instancethe instance
callbackthe callback to set. If NULL, return the existing callback
Returns
The existing (and previous) callback.
See Also
lcb_connect()
lcb_get_bootstrap_status()
Examples:
example/libeventdirect/main.c.
lcb_error_t lcb_get_bootstrap_status ( lcb_t  instance)

Gets the initial bootstrap status.

This is an alternative to using the lcb_bootstrap_callback() and may be used after the initial lcb_connect() and lcb_wait() sequence.

Parameters
instance
Returns
LCB_SUCCESS if properly bootstrapped or an error code otherwise.
Attention
Calling this function only makes sense during instantiation.
Stability
Committed:
Examples:
example/minimal/minimal.c.
void lcb_refresh_config ( lcb_t  instance)

Force the library to refetch the cluster configuration.

Stability
Uncommitted:

The library by default employs various heuristics to determine if a new configuration is needed from the cluster. However there are some situations in which an application may wish to force a refresh of the configuration:

  • If a specific node has been failed over and the library has received a configuration in which there is no master node for a given key, the library will immediately return the error LCB_NO_MATCHING_SERVER for the given item and will not request a new configuration. In this state, the client will not perform any network I/O until a request has been made to it using a key that is mapped to a known active node.
  • The library's heuristics may have failed to detect an error warranting a configuration change, but the application either through its own heuristics, or through an out-of-band channel knows that the configuration has changed.

This function is provided as an aid to assist in such situations

If you wish for your application to block until a new configuration is received, you must call lcb_wait3() with the LCB_WAIT_NO_CHECK flag as this function call is not bound to a specific operation. Additionally there is no status notification as to whether this operation succeeded or failed (the configuration callback via lcb_set_configuration_callback() may provide hints as to whether a configuration was received or not, but by no means should be considered to be part of this function's control flow).

In general the use pattern of this function is like so:

unsigned retries = 5;
do {
retries--;
err = lcb_get(instance, cookie, ncmds, cmds);
if (err == LCB_NO_MATCHING_SERVER) {
lcb_refresh_config(instance);
usleep(100000);
lcb_wait3(instance, LCB_WAIT_NO_CHECK);
} else {
break;
}
} while (retries);
if (err == LCB_SUCCESS) {
lcb_wait3(instance, 0); // equivalent to lcb_wait(instance);
} else {
printf("Tried multiple times to fetch the key, but its node is down\n");
}
lcb_configuration_callback lcb_set_configuration_callback ( lcb_t  ,
lcb_configuration_callback   
)
Stability
Uncommitted:
void lcb_destroy ( lcb_t  instance)

Destroy (and release all allocated resources) an instance of lcb.

Using instance after calling destroy will most likely cause your application to crash.

Note that any pending operations will not have their callbacks invoked.

Parameters
instancethe instance to destroy.
Stability
Committed:
Examples:
example/libeventdirect/main.c, and example/minimal/minimal.c.
lcb_destroy_callback lcb_set_destroy_callback ( lcb_t  ,
lcb_destroy_callback   
)

Set the callback to be invoked when the instance is destroyed asynchronously.

Returns
the previous callback.
void lcb_destroy_async ( lcb_t  instance,
const void *  arg 
)

Asynchronously schedule the destruction of an instance.

This function provides a safe way for asynchronous environments to destroy the lcb_t handle without worrying about reentrancy issues.

Parameters
instance
arga pointer passed to the callback.

While the callback and cookie are optional, they are very much recommended for testing scenarios where you wish to ensure that all resources allocated by the instance have been closed. Specifically when the callback is invoked, all timers (save for the one actually triggering the destruction) and sockets will have been closed.

As with lcb_destroy() you may call this function only once. You may not call this function together with lcb_destroy as the two are mutually exclusive.

If for whatever reason this function is being called in a synchronous flow, lcb_wait() must be invoked in order for the destruction to take effect

See Also
lcb_set_destroy_callback
Stability
Committed:
lcb_error_t lcb_create_io_ops ( lcb_io_opt_t *  op,
const struct lcb_create_io_ops_st options 
)

Create a new instance of one of the library-supplied io ops types.

Parameters
opWhere to store the io ops structure
optionsHow to create the io ops structure
Returns
LCB_SUCCESS on success
Stability
Uncommitted:
Examples:
example/libeventdirect/main.c.
lcb_error_t lcb_destroy_io_ops ( lcb_io_opt_t  op)

Destory io ops instance.

Parameters
opops structure
Returns
LCB_SUCCESS on success
Stability
Uncommitted:

Data Structure Documentation

struct lcb_create_st3

Structure for lcb_create().

See Also
Basic Library Routines
Data Fields
const char * connstr Connection string.
const char * username Username for bucket.

Unused as of Server 2.5

const char * passwd Password for bucket.
void * _pad_bucket
struct lcb_io_opt_st * io IO Options.
lcb_type_t type
struct lcb_create_st
Data Fields
int version Set this to 3
union lcb_create_st v
struct lcb_IOCREATEOPTS_BUILTIN

IO Creation for builtin plugins.

Data Fields
lcb_io_ops_type_t type The predefined type you want to create.
void * cookie Plugin-specific argument.
struct lcb_IOCREATEOPS_FUNCTIONPOINTER

I/O Creation for function pointers.

Data Fields
lcb_io_create_fn create Function used to create the IO ops.
void * cookie cookie parameter passed to function
struct lcb_create_io_ops_st

uncommitted

Examples:
example/libeventdirect/main.c.
Data Fields
int version
union lcb_create_io_ops_st v

Typedef Documentation

typedef void(* lcb_bootstrap_callback)(lcb_t instance, lcb_error_t err)

Bootstrap callback.

Invoked once the instance is ready to perform operations

Parameters
instanceThe instance which was bootstrapped
errThe error code received. If this is not LCB_SUCCESS then the instance is not bootstrapped and must be recreated
Attention
This callback only receives information during instantiation.
Stability
Committed:
typedef void(* lcb_configuration_callback)(lcb_t instance, lcb_configuration_t config)

Receive notification upon cluster configuration.

This callback may be used as a hook for the application to notify it that operations may start being scheduled.

Parameters
instanceThe instance who received the new configuration
configThe kind of configuration received
Stability
Uncommitted:
typedef void(* lcb_destroy_callback)(const void *cookie)

Callback received when instance is about to be destroyed.

Parameters
cookiecookie passed to lcb_destroy_async()

Enumeration Type Documentation

enum lcb_type_t

Handle types.

See Also
lcb_create_st3::type
Enumerator
LCB_TYPE_BUCKET 

Handle for data access (default)

LCB_TYPE_CLUSTER 

Handle for administrative access.

Flags for lcb_wait3()

Enumerator
LCB_WAIT_DEFAULT 

Behave like the old lcb_wait()

LCB_WAIT_NOCHECK 

Do not check pending operations before running the event loop.

By default lcb_wait() will traverse the server list to check if any operations are pending, and if nothing is pending the function will return without running the event loop. This is usually not necessary for applications which already only call lcb_wait() when they know they have scheduled at least one command.

Argument indicating configuration change type.

See Also
lcb_set_configuration_callback() uncommitted
Enumerator
LCB_CONFIGURATION_NEW 

New configuration (initial bootstrap).

This status code is received only once per instance

LCB_CONFIGURATION_CHANGED 

Configuration updated.

LCB_CONFIGURATION_UNCHANGED 

Configuration propagated from cluster, but matches our current one.

Built-in I/O plugins.

Stability
Committed:
Enumerator
LCB_IO_OPS_LIBEVENT 

Integrate with the libevent loop.

See lcb_create_libevent_io_opts()