libcouchbase is an asynchronous library for connecting to a Couchbase server and performing data operations.
This contains the API documentation for the library. The documentation consists of both internal and public interfaces.
Using the library is comprised of these steps:
- Create an instance (See lcb_create())
- Install callbacks (See lcb_set_get_callback())
- Schedule an operation (e.g. lcb_get())
- Wait for the operation to complete (lcb_wait())
libcouchbase is an asynchronous library which means that operation results are passed to callbacks you define rather than being returned from functions.
Callbacks are passed a cookie
parameter which is a user-defined pointer (i.e. your own pointer which can be NULL
) to associate a specific command with a specific callback invocation.
For simple synchronous use, you will need to call lcb_wait() after each set of scheduled operations. During lcb_wait() the library will block for I/O and invoke your callbacks as the results for the operations arrive.
For non-synchronous use cases you can integrate with a variety of event loops via the various plugins, or integrate one yourself via the IOPS
API (see Network I/O)
Modifying the library's settings (for example, timeout settings) may be done via the lcb_cntl() interface (see Setting List) or via some environment variables (see Environment Variables)
Using the headers and libraries
Using the libcouchbase headers is simple. Simply:
into your application.
To link, simply link against libcouchbase
(e.g. -lcouchbase
).
See Interface Attributes for interface stability taxonomy and Thread Safety for information on programming in threaded environments
Minimal example usage
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#ifdef _WIN32
#define PRIx64 "I64x"
#else
#include <inttypes.h>
#endif
{
exit(EXIT_FAILURE);
}
{
if (rc == LCB_SUCCESS) {
const char *key;
size_t nkey;
uint64_t cas;
lcb_respstore_key(resp, &key, &nkey);
fprintf(stderr, "KEY: %.*s\n", (int)nkey, key);
lcb_respstore_cas(resp, &cas);
fprintf(stderr, "CAS: 0x%" PRIx64 "\n", cas);
} else {
}
}
{
if (rc == LCB_SUCCESS) {
const char *key, *value;
size_t nkey, nvalue;
uint64_t cas;
uint32_t flags;
lcb_respget_key(resp, &key, &nkey);
fprintf(stderr, "KEY: %.*s\n", (int)nkey, key);
lcb_respget_cas(resp, &cas);
fprintf(stderr, "CAS: 0x%" PRIx64 "\n", cas);
lcb_respget_value(resp, &value, &nvalue);
lcb_respget_flags(resp, &flags);
fprintf(stderr, "VALUE: %.*s\n", (int)nvalue, value);
fprintf(stderr, "FLAGS: 0x%x\n", flags);
} else {
}
}
int main(int argc, char *argv[])
{
lcb_CREATEOPTS *create_options = NULL;
lcb_CMDSTORE *scmd;
lcb_CMDGET *gcmd;
if (argc < 2) {
fprintf(stderr, "Usage: %s couchbase://host/bucket [ password [ username ] ]\n", argv[0]);
exit(EXIT_FAILURE);
}
lcb_createopts_connstr(create_options, argv[1], strlen(argv[1]));
if (argc > 3) {
lcb_createopts_credentials(create_options, argv[2], strlen(argv[2]), argv[3], strlen(argv[3]));
}
lcb_createopts_destroy(create_options);
if (err != LCB_SUCCESS) {
die(NULL, "Couldn't create couchbase handle", err);
}
if (err != LCB_SUCCESS) {
die(instance, "Couldn't schedule connection", err);
}
if (err != LCB_SUCCESS) {
die(instance, "Couldn't bootstrap from cluster", err);
}
lcb_cmdstore_key(scmd, "key", strlen("key"));
lcb_cmdstore_value(scmd, "value", strlen("value"));
err = lcb_store(instance, NULL, scmd);
lcb_cmdstore_destroy(scmd);
if (err != LCB_SUCCESS) {
die(instance, "Couldn't schedule storage operation", err);
}
fprintf(stderr, "Will wait for storage operation to complete..\n");
lcb_cmdget_create(&gcmd);
lcb_cmdget_key(gcmd, "key", strlen("key"));
err = lcb_get(instance, NULL, gcmd);
if (err != LCB_SUCCESS) {
die(instance, "Couldn't schedule retrieval operation", err);
}
lcb_cmdget_destroy(gcmd);
fprintf(stderr, "Will wait to retrieve item..\n");
return 0;
}
Configuring and Tuning the library
The library may be configured either programmatically via lcb_cntl(), or via the environment (see Environment Variables)
Simple Usage Steps
- Create an
lcb_t
handle. This is done via lcb_create()
- Schedule the initial connection, this is done via lcb_connect()
- Wait for the initial connection to complete, via lcb_wait()
- Install the callbacks for retrieval and storage (lcb_set_get_callback(), lcb_set_stor_callback()).
- Set up a command structure for storing an item, i.e. lcb_store_cmd_t.
- Schedule the operation via lcb_store(). You will also likely want to pass a
cookie
parameter along with it so that you can associate your application's structures via the callback.
- Invoke lcb_wait(). Your callback will be invoked with the result of the storage operation.
- Stability
- Internal:
Public vs Internal APIs
The Public API section is where you should begin browsing to develop with the library. Any sections not contained within the public API are internal and are provided to aid in developing new features and fixing bugs within the library itself.
Internal Header Layouts
The internal headers are organized like so:
- <lcbio/lcbio.h> - I/O Core
- <mc/mcreq.h> - Memcached packet codecs
- <netbuf/netbuf.h> - Write buffer implementation
- <rdb/rope.h> - Read buffer implementation
- <mcserver/mcserver.h> - Memcached client I/O
- <mcserver/negotiate.h> - Memcached client initial SASL handling
- <bucketconfig/clconfig.h> - Couchbase cluster configuration retrieval
- <packetutils.h> - Utility for response packets
- <src/retryq.h> - Retry queue for failed packets
- <src/internal.h> - Other internal functions not in the above categories
In addition to these files, there are several non-core files which exist to provide simple utilities which are not specific to the library:
- <list.h> - Double-linked list
- <sllist.h>, <sllist-inl.h> - Single linked list
- <genhash.h> - Hashtable
- <hashset.h> - Set of unique elements
- <hostlist.h> - Host/Port structures and lists
Prerequisite Knowledge
libcouchbase is a cross platform C library used to interact with Couchbase Server. It is assumed that you know about:
- Key-Value stores
- The C language
- Asynchronous and non-blocking programming.
To develop with the I/O integration APIs, you will need to know about: