Name

lcb_cntl — Tune libcouchbase internals

Synopsis

cc [ flag ... ] file... -lcouchbase [ library ... ]
#include <libcouchbase/couchbase.h>
lcb_error_t lcb_cntl(lcb_t instance, int mode, int cmd, void *arg);

DESCRIPTION

This function exposes an ioctl/fcntl-like interface to read and write various configuration properties to and from an lcb_t handle.

instance
The instance to modify
mode
One of LCB_CNTL_GET (to retrieve a setting) or LCB_CNTL_SET (to modify a setting). Note that not all configuration properties support SET.
cmd

The specific command/property to modify. This is one of the LCB_CNTL_* constants defined in this file. Note that it is safe (and even recommanded) to use the raw numeric value (i.e. to be backwards and forwards compatible with libcouchbase versions), as they are not subject to change.

Using the actual value may be useful in ensuring your application will still compile with an older libcouchbase version (though you may get a runtime error (see return) if the command is not supported

arg
The argument passed to the configuration handler. The actual type of this pointer is dependent on the command in question. Typically for GET operations, the value of arg is set to the current configuration value; and for SET operations, the current configuration is updated with the contents of *arg.

Available Commands

LCB_CNTL_OP_TIMEOUT (lcb_uint32_t*)

Set or get operation timeout in microseconds. Default is 2500000 (2.5 seconds).

lcb_uint32_t tmo = 3500000;
lcb_cntl(instance, LCB_CNTL_SET, LCB_CNTL_OP_TIMEOUT, &tmo);
LCB_CNTL_CONFIGURATION_TIMEOUT (lcb_uint32_t*)

Set or get the per-instance setting for the connection timeout. This is how long the client will wait to obtain the initial configuration as well as the time the client will wait to obtain new configurations when needed. Default is 5000000 (5 seconds)

lcb_uint32_t tmo = 3500000;
lcb_cntl(instance, LCB_CNTL_SET, LCB_CNTL_CONFIGURATION_TIMEOUT, &tmo);
LCB_CNTL_VIEW_TIMEOUT (lcb_uint32_t*)

Set or get view (map/reduce) timeout in microseconds. Default is 75000000 (75 seconds).

lcb_uint32_t tmo = 30000000;
lcb_cntl(instance, LCB_CNTL_SET, LCB_CNTL_VIEW_TIMEOUT, &tmo);
LCB_CNTL_HTTP_TIMEOUT (lcb_uint32_t*)

Set or get the HTTP timeout. This is used for administrative (LCB_HTTP_TYPE_MANAGEMENT) or raw (LCB_HTTP_TYPE_RAW) requests. Default is 75000000 (75 seconds)

lcb_uint32_t tmo = 20000000;
lcb_cntl(instance, LCB_CNTL_SET, LCB_CNTL_HTTP_TIMEOUT, &tmo);
LCB_CNTL_RBUFSIZE (lcb_size_t*)

Set or get default read buffer size (this is not a socket option). Default is 32768 bytes.

lcb_size_t sz = 8192;
lcb_cntl(instance, LCB_CNTL_SET, LCB_CNTL_RBUFSIZE, &sz);
LCB_CNTL_WBUFSIZE (lcb_size_t*)

Set or get default write buffer size (this is not a socket option). Default is 32768 bytes.

lcb_size_t sz = 8192;
lcb_cntl(instance, LCB_CNTL_SET, LCB_CNTL_WBUFSIZE, &sz);
LCB_CNTL_HANDLETYPE (lcb_type_t*)

Get the handle type.

lcb_type_t type;
lcb_cntl(instance, LCB_CNTL_GET, LCB_CNTL_HANDLETYPE, &type);
switch (type) {
    case LCB_TYPE_BUCKET:
        printf("handle connected to bucket\n");
        break;
    case LCB_TYPE_CLUSTER:
        printf("handle connected to cluster\n");
        break;
}
LCB_CNTL_VBCONFIG (VBUCKET_CONFIG_HANDLE*)

Get the handle of the cluster configuration

#include <libvbucket/vbucket.h>
VUCKET_CONFIG_HANDLE conf;
const char *password;
lcb_cntl(instance, LCB_CNTL_GET, LCB_CNTL_VBCONFIG, &conf);
password = vbucket_config_get_password(conf);
LCB_CNTL_IOPS (lcb_io_opt_t*)

Get the implementation of IO stucture (the plugin gist)

lcb_io_opt_t io;
lcb_cntl(instance, LCB_CNTL_GET, LCB_CNTL_IOPS, &io);
printf("IO plugin version %d\n", io->version);
if (io->version == 0) {
    io->v.v0.run_event_loop(io);
}
LCB_CNTL_VBMAP (lcb_cntl_vbinfo_t*)

Get the vBucket ID for a given key, based on the current configuration The vbucket field in he structure will be modified.

Structure layout:

typedef struct lcb_cntl_vbinfo_st lcb_cntl_vbinfo_t;
struct lcb_cntl_vbinfo_st {
    int version;
    union {
        struct {
            /** Input parameters */
            const void *key;
            lcb_size_t nkey;
            /** Output */
            int vbucket;
            int server_index;
        } v0;
    } v;
};

Example:

char key[] = "foo";
lcb_cntl_vbinfo_t info;
info.version = 0;
info.v.v0.key = key;
info.v.v0.nkey = strlen(key);
lcb_cntl(instance, LCB_CNTL_GET, LCB_CNTL_VBMAP, &info);
printf("vBucket ID of \"%s\" is %d\n", key, info.v.v0.vbucket);
LCB_CNTL_MEMDNODE_INFO lcb_cntl_server_t*

Get information about a memcached node. Note that all fields in this structure are ready only and are only valid until one of the following happens:

  1. Another libcouchbase API function is called
  2. The IOPS loop regains control

Structure layout:

typedef struct lcb_cntl_server_st lcb_cntl_server_t;
struct lcb_cntl_server_st {
    int version;
    union {
        struct {
            /** Server index to query */
            int index;
            /** NUL-terminated string containing the address */
            const char *host;
            /** NUL-terminated string containing the port */
            const char *port;
            /** Whether the node is connected */
            int connected;
            /**
             * Socket information. If a v0 IO plugin is being
             * used, the sockfd is set to the socket
             * descriptor. If a v1 plugin is being used, the
             * sockptr is set to point to the appropriate
             * structure.
             *
             * Note that you *MAY* perform various
             * 'setsockopt' calls on the sockfd (though it is
             * your responsibility to ensure those options are
             * valid); however the actual socket descriptor
             * may change in the case of a cluster
             * configuration update.
             */
            union {
                lcb_socket_t sockfd;
                lcb_sockdata_t *sockptr;
            } sock;
        } v0;
    } v;
};

Example:

lcb_cntl_server_t node;
node.version = 0;
node.v.v0.index = 0; /* first node */
lcb_cntl(instance, LCB_CNTL_GET, LCB_CNTL_MEMDNODE_INFO, &node);
printf("node \"%s:%s\" is %s\n", node.v.v0.host, node.v.v0.port,
       node.v.v0.connected ? "connected" : "is not connected");
LCB_CNTL_CONFIGNODE_INFO (lcb_io_opt_t*)

Get information about the configuration node. Semantics of LCB_CNTL_MEMDNODE_INFO apply here as well, but v.v0.index field is ignored, obviously.

lcb_cntl_server_t node;
node.version = 0;
lcb_cntl(instance, LCB_CNTL_GET, LCB_CNTL_CONFIGNODE_INFO, &node);
printf("listening configuration from \"%s:%s\"\n",
       node.v.v0.host, node.v.v0.port);
LCB_CNTL_SYNCMODE (lcb_syncmode_t*)

Set or get "synchmode" behaviour. The following synchronous models are defined (default LCB_ASYNCHRONOUS):

LCB_ASYNCHRONOUS

This is the default and all calls to libcouchbase are non-blocking (except for lcb_wait().

LCB_SYNCHRONOUS

In synchronous mode the function will block until either the operation is complete, or a hard error occurs. Operating in synchronous mode is the same as calling lcb_wait() after each function call.

lcb_syncmode_t mode = LCB_SYNCHRONOUS;
lcb_cntl(instance, LCB_CNTL_SET, LCB_CNTL_SYNCMODE, &mode);
LCB_CNTL_IP6POLICY (lcb_ipv6_t*)

Get or set IPv4/IPv6 selection policy. The following settings for IPv6 is defined (default LCB_IPV6_DISABLED):

LCB_IPV6_DISABLED

Disable all use of IPv6.

LCB_IPV6_ONLY

Disable all use of IPv4, and only connect to IPv6 hosts

LCB_IPV6_ALLOW

Allow a mix of IPv4 and IPv6.

lcb_ipv6_t mode = LCB_IPV6_ALLOW;
lcb_cntl(instance, LCB_CNTL_SET, LCB_CNTL_IP6POLICY, &mode);
LCB_CNTL_CONFERRTHRESH (lcb_size_t*)

Get or set the configuration error threshold. This number indicates how many network/mapping/not-my-vbucket errors are received before a configuration update is requested again (default 100).

lcb_size_t num_events = 10;
lcb_cntl(instance, LCB_CNTL_SET, LCB_CNTL_CONFERRTHRESH, &num_events);
LCB_CNTL_DURABILITY_TIMEOUT (lcb_uint32_t*)

Get or set the default timeout for durability operations. Default is 5000000 (5 seconds)

lcb_uint32_t tmo = 7500000; /* 7.5 seconds */
lcb_cntl(instance, LCB_CNTL_SET, LCB_CNTL_DURABILITY_TIMEOUT, &tmo);
LCB_CNTL_DURABILITY_INTERVAL (lcb_uint32_t*)

Get or set the default durability polling interval Default is 100000 (100 milliseconds)

lcb_uint32_t tmo = 50000; /* 50 milliseconds */
lcb_cntl(instance, LCB_CNTL_SET, LCB_CNTL_DURABILITY_INTERVAL, &tmo);
LCB_CNTL_IOPS_DEFAULT_TYPES (struct lcb_cntl_iops_info_st*)

Get the default IOPS types for this build. This provides a convenient way to determine what libcouchbase will use for IO when not explicitly specifying an iops structure to lcb_create().

Pass NULL as the instance, as this retrieves a global setting.

The information is returned in a lcb_cntl_iops_info_st structure, which is defined in <libcouchbase/cntl.h>:

struct lcb_cntl_iops_info_st {
    int version; /* set this to 0 */
    union {
        struct {
            /**
             * Pass here options, used to create IO structure with
             * link:lcb_create_io_ops.3.html[lcb_create_io_ops(3)], to find out whether the library
             * will override them in the current environment
             */
            const struct lcb_create_io_ops_st *options;
            /**
             * The default IO ops type. This is hard-coded into the library
             * and is used if nothing else was specified in creation options
             * or the environment
             */
            lcb_io_ops_type_t os_default;
            /**
             * The effective plugin type after reading environment variables.
             * If this is set to 0, then a manual (non-builtin) plugin has been
             * specified.
             */
            lcb_io_ops_type_t effective;
        } v0;
    } v;
};

Example 1: Get default IO backend for current OS

struct lcb_cntl_iops_info_st info;
memset(&info, 0, sizeof(info));
lcb_cntl(NULL, LCB_CNTL_GET, LCB_CNTL_IOPS_DEFAULT_TYPES, &info);
printf("libcouchbase by default will try to use: ");
switch (info.v.v0.os_default) {
case LCB_IO_OPS_LIBEVENT:
    printf("libevent");
    break;
case LCB_IO_OPS_LIBEV:
    printf("libev");
    break;
case LCB_IO_OPS_SELECT:
case LCB_IO_OPS_WINSOCK:
    printf("select(2)");
    break;
case LCB_IO_OPS_WINIOCP:
    printf("windows IOCP");
    break;
case LCB_IO_OPS_LIBUV:
    printf("libuv");
    break;
default:
    printf("custom (newer?)");
    break;
}
printf(" IO backend\n");

Example 2: Check whether the IO backed has been overriden by user

lcb_create_io_ops_st *options;
...
struct lcb_cntl_iops_info_st info;
info.version = 0;
info.v.v0.options = options;
lcb_cntl(NULL, LCB_CNTL_GET, LCB_CNTL_IOPS_DEFAULT_TYPES, &info);
if (options->version == 0 && info.v.v0.effective == options->v.v0.type) {
    printf("the options will be overriden. %d => %d\n",
           options->v.v0.type, info.v.v0.effective);
} else {
    printf("the current environment won't override these options\n");
}
LCB_CNTL_IOPS_DLOPEN_DEBUG (int*)

Get or set the verbose printing of dynamic loading of IO plugins.

The information printed can be useful in determining why a plugin failed to load. This setting can also be controlled via the "LIBCOUCHBASE_DLOPEN_DEBUG" environment variable (and if enabled from the environment, will override the setting mentioned here).

Pass NULL as the instance, as this accesses a global setting

LCB_CNTL_SKIP_CONFIGURATION_ERRORS_ON_CONNECT (int*)

Get/Set the per-instance setting to control connection behaviour when config node doesn’t seem to be member of the cluster. By default the setting is false (0), which mean to propagate LCB_BUCKET_ENOENT or LCB_AUTH_ERROR immediately from the first node and look at the next entry in list only on network issues. But for cases when the node list is rather constant, and the some nodes might be removed from the deployment and still listen on configuration port, the caller can set this setting to true (non zero), to force checking bucket on all nodes in the list until it found working.

int check = 1;
lcb_cntl(instance, LCB_CNTL_SET,
    LCB_CNTL_SKIP_CONFIGURATION_ERRORS_ON_CONNECT, &check);

RETURN VALUE

LCB_NOT_SUPPORTED if the code is unrecognized LCB_EINVAL if there was a problem with the argument (typically for SET) other error codes depending on the command.

ATTRIBUTES

See lcb_attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE ATTRIBUTE VALUE

Interface Stability

Committed

MT-Level

MT-Safe

COPYRIGHT

Copyright 2010-2013 Couchbase, Inc.

SEE ALSO

Learn more at http://www.couchbase.com/communities/c.

libcouchbase(3lib), lcb_create(3couchbase), lcb_attributes(5)