Couchbase C Client  3.0.5
Asynchronous C Client for Couchbase
Introduction

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:

  1. Create an instance (See lcb_create())
  2. Install callbacks (See lcb_set_get_callback())
  3. Schedule an operation (e.g. lcb_get())
  4. 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

/* -*- Mode: C; tab-width: 4; c-basic-offset: 4; indent-tabs-mode: nil -*- */
/*
* Copyright 2012-2020 Couchbase, Inc.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
#include <stdio.h>
#include <stdlib.h>
#include <string.h> /* strlen */
#ifdef _WIN32
#define PRIx64 "I64x"
#else
#include <inttypes.h>
#endif
static void die(lcb_INSTANCE *instance, const char *msg, lcb_STATUS err)
{
fprintf(stderr, "%s. Received code 0x%X (%s)\n", msg, err, lcb_strerror_short(err));
exit(EXIT_FAILURE);
}
static void store_callback(lcb_INSTANCE *instance, int cbtype, const lcb_RESPSTORE *resp)
{
lcb_STATUS rc = lcb_respstore_status(resp);
fprintf(stderr, "=== %s ===\n", lcb_strcbtype(cbtype));
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 {
die(instance, lcb_strcbtype(cbtype), rc);
}
}
static void get_callback(lcb_INSTANCE *instance, int cbtype, const lcb_RESPGET *resp)
{
lcb_STATUS rc = lcb_respget_status(resp);
fprintf(stderr, "=== %s ===\n", lcb_strcbtype(cbtype));
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 {
die(instance, lcb_strcbtype(cbtype), rc);
}
}
int main(int argc, char *argv[])
{
lcb_INSTANCE *instance;
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_create(&create_options, LCB_TYPE_BUCKET);
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]));
}
err = lcb_create(&instance, create_options);
lcb_createopts_destroy(create_options);
if (err != LCB_SUCCESS) {
die(NULL, "Couldn't create couchbase handle", err);
}
err = lcb_connect(instance);
if (err != LCB_SUCCESS) {
die(instance, "Couldn't schedule connection", err);
}
err = lcb_get_bootstrap_status(instance);
if (err != LCB_SUCCESS) {
die(instance, "Couldn't bootstrap from cluster", err);
}
/* Assign the handlers to be called for the operation types */
lcb_cmdstore_create(&scmd, LCB_STORE_UPSERT);
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);
}
/* The store_callback is invoked from lcb_wait() */
fprintf(stderr, "Will wait for storage operation to complete..\n");
/* Now fetch the item back */
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);
/* Likewise, the get_callback is invoked from here */
fprintf(stderr, "Will wait to retrieve item..\n");
/* Now that we're all done, close down the connection handle */
lcb_destroy(instance);
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

  1. Create an lcb_t handle. This is done via lcb_create()
  2. Schedule the initial connection, this is done via lcb_connect()
  3. Wait for the initial connection to complete, via lcb_wait()
  4. Install the callbacks for retrieval and storage (lcb_set_get_callback(), lcb_set_stor_callback()).
  5. Set up a command structure for storing an item, i.e. lcb_store_cmd_t.
  6. 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.
  7. 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:

  • Socket APIs
  • Event loops
lcb_strerror_short
LCB_INTERNAL_API const char * lcb_strerror_short(lcb_STATUS error)
Get a shorter textual description of an error message.
lcb_RESPSTORE
struct lcb_RESPSTORE_ lcb_RESPSTORE
Schedule a single storage request.
Definition: couchbase.h:941
lcb_wait
lcb_STATUS lcb_wait(lcb_INSTANCE *instance, lcb_WAITFLAGS flags)
Wait for completion of scheduled operations.
LCB_CALLBACK_STORE
@ LCB_CALLBACK_STORE
lcb_store()
Definition: couchbase.h:469
lcb_get_bootstrap_status
lcb_STATUS lcb_get_bootstrap_status(lcb_INSTANCE *instance)
Gets the initial bootstrap status.
lcb_connect
lcb_STATUS lcb_connect(lcb_INSTANCE *instance)
Schedule the initial connection This function will schedule the initial connection for the handle.
LCB_WAIT_DEFAULT
@ LCB_WAIT_DEFAULT
Behave like the old lcb_wait()
Definition: couchbase.h:1768
lcb_create
lcb_STATUS lcb_create(lcb_INSTANCE **instance, const lcb_CREATEOPTS *options)
Create an instance of lcb.
lcb_STATUS
lcb_STATUS
Error codes returned by the library.
Definition: error.h:202
lcb_INSTANCE
struct lcb_st lcb_INSTANCE
Library handle representing a connection to a cluster and its data buckets.
Definition: couchbase.h:35
LCB_CALLBACK_GET
@ LCB_CALLBACK_GET
lcb_get()
Definition: couchbase.h:468
lcb_strcbtype
const char * lcb_strcbtype(int cbtype)
Returns the type of the callback as a string.
lcb_RESPGET
struct lcb_RESPGET_ lcb_RESPGET
Command for retrieving a single item.
Definition: couchbase.h:685
couchbase.h
Main header file for Couchbase.
LCB_STORE_UPSERT
@ LCB_STORE_UPSERT
The default storage mode.
Definition: couchbase.h:857
lcb_destroy
void lcb_destroy(lcb_INSTANCE *instance)
Destroy (and release all allocated resources) an instance of lcb.
LCB_TYPE_BUCKET
@ LCB_TYPE_BUCKET
Handle for data access (default)
Definition: couchbase.h:255
lcb_install_callback
lcb_RESPCALLBACK lcb_install_callback(lcb_INSTANCE *instance, int cbtype, lcb_RESPCALLBACK cb)
lcb_RESPCALLBACK
void(* lcb_RESPCALLBACK)(lcb_INSTANCE *instance, int cbtype, const lcb_RESPBASE *resp)
Callback invoked for responses.
Definition: couchbase.h:551