Couchbase C Client
2.5.6
|
Adjust tunables for the client.
The constants in this file are used to control the behavior of the library. All of the operations above may be passed as the cmd
parameter to the lcb_cntl() function, thus:
will retrieve the setting of LCB_CNTL_FOO
into something
.
You may also use the lcb_cntl_string() function, which operates on strings and can set various configuration properties fairly simply. Note however that string names are subject to change, and not all configuration directives have a string alias:
Of the commands listed below, some will be read-only (i.e. you may only read the setting using the LCB_CNTL_GET mode
), some will be write-only (i.e. you may only modify the setting, and use LCB_CNTL_SET for the mode
) and some will be both readable and writable.
Along the documentation of each specific command, there is a table displaying the modes supported and the expected pointer type to be passed as the arg
value into lcb_cntl(). Note that some read-write commands require different pointer types depending on whether the mode
is retrieval or storage.
Timeout settings control how long the library will wait for a certain event before proceeding to the next course of action (which may either be to try a different operation or fail the current one, depending on the specific timeout).
Timeouts are specified in microseconds stored within an lcb_U32
.
Note that timeouts in libcouchbase are implemented via an event loop scheduler. As such their accuracy and promptness is limited by how often the event loop is invoked and how much wall time is spent in each of their handlers. Specifically if you issue long running blocking calls within any of the handlers (and this means any of the library's callbacks) then the timeout accuracy will be impacted.
Further behavior is dependent on the event loop plugin itself and how it schedules timeouts.
Macros | |
#define | LCB_CNTL_OP_TIMEOUT |
Operation Timeout. More... | |
#define | LCB_CNTL_VIEW_TIMEOUT |
Views Timeout This is the I/O timeout for HTTP requests issues with LCB_HTTP_TYPE_VIEWS. More... | |
#define | LCB_CNTL_N1QL_TIMEOUT |
N1QL Timeout This is the I/O timeout for N1QL queries, issued via lcb_n1ql_query() More... | |
#define | LCB_CNTL_BUCKETNAME |
Get the name of the bucket This returns the name of the bucket this instance is connected to, or NULL if not yet connected to a bucket. More... | |
#define | LCB_CNTL_HANDLETYPE |
Get the handle type. More... | |
#define | LCB_CNTL_VBCONFIG |
Get the vBucket handle. More... | |
#define | LCB_CNTL_IOPS |
Get the iops implementation instance. More... | |
#define | LCB_CNTL_VBMAP |
Get the vBucket ID for a given key, based on the current configuration. More... | |
#define | LCB_CNTL_CONFERRTHRESH |
Configuration error threshold. More... | |
#define | LCB_CNTL_DURABILITY_TIMEOUT |
Default timeout for lcb_durability_poll()This is the time the client will spend sending repeated probes to a given key's vBucket masters and replicas before they are deemed not to have satisfied the durability requirements. More... | |
#define | LCB_CNTL_DURABILITY_INTERVAL |
Polling grace interval for lcb_durability_poll() More... | |
#define | LCB_CNTL_HTTP_TIMEOUT |
Timeout for non-views HTTP requests. More... | |
#define | LCB_CNTL_IOPS_DLOPEN_DEBUG |
Print verbose plugin load information to console. More... | |
#define | LCB_CNTL_CONFIGURATION_TIMEOUT |
Initial bootstrap timeout. More... | |
#define | LCB_CNTL_RANDOMIZE_BOOTSTRAP_HOSTS |
Randomize order of bootstrap nodes. More... | |
#define | LCB_CNTL_CONFIG_CACHE_LOADED |
Determine if file-based configuration has been loaded. More... | |
#define | LCB_CNTL_FORCE_SASL_MECH |
Force a specific SASL mechanism. More... | |
#define | LCB_CNTL_MAX_REDIRECTS |
Maximum number of HTTP redirects to follow Set how many redirects the library should follow for the single request. More... | |
#define | LCB_CNTL_CONFDELAY_THRESH |
Refresh Throttling. More... | |
#define | LCB_CNTL_CONFIG_TRANSPORT |
Get the transport used to fetch cluster configuration. More... | |
#define | LCB_CNTL_CONFIG_NODE_TIMEOUT |
Per-node configuration timeout. More... | |
#define | LCB_CNTL_HTCONFIG_IDLE_TIMEOUT |
Idling/Persistence for HTTP bootstrap. More... | |
#define | LCB_CNTL_CHANGESET |
Get the current SCM changeset for the library binary. More... | |
#define | LCB_CNTL_CONFIGCACHE |
file used for the configuration cache. More... | |
#define | LCB_CNTL_CONFIGCACHE_RO |
File used for read-only configuration cache. More... | |
#define | LCB_CNTL_SSL_MODE |
Get SSL Mode. More... | |
#define | LCB_CNTL_SSL_CERT |
Get SSL Certificate path. More... | |
#define | LCB_CNTL_SSL_CACERT |
#define | LCB_RETRYOPT_CREATE(mode, policy) |
Create a retry setting value. More... | |
#define | LCB_RETRYOPT_GETMODE(u) |
#define | LCB_RETRYOPT_GETPOLICY(u) |
#define | LCB_CNTL_RETRYMODE |
Set retry policies. More... | |
#define | LCB_CNTL_HTCONFIG_URLTYPE |
Set the URL selection mode. More... | |
#define | LCB_CNTL_SYNCDESTROY |
#define | LCB_CNTL_CONLOGGER_LEVEL |
#define | LCB_CNTL_CONLOGGER_FP |
#define | LCB_CNTL_DETAILED_ERRCODES |
#define | LCB_CNTL_RETRY_INTERVAL |
#define | LCB_CNTL_RETRY_BACKOFF |
#define | LCB_CNTL_RETRY_NMV_IMM |
#define | LCB_CNTL_HTTP_POOLSIZE |
#define | LCB_CNTL_HTTP_REFRESH_CONFIG_ON_ERROR |
uncommitted Determine whether or not a new configuration should be received when an error is received over the HTTP API (i.e. More... | |
#define | LCB_CNTL_SCHED_IMPLICIT_FLUSH |
#define | LCB_CNTL_FETCH_MUTATION_TOKENS |
#define | LCB_CNTL_DURABILITY_MUTATION_TOKENS |
#define | LCB_CNTL_MUTATION_TOKENS_SUPPORTED |
#define | LCB_CNTL_RESET_TIMEOUT_ON_WAIT |
#define | LCB_CNTL_N1QL_CLEARACHE |
#define | LCB_CNTL__MAX |
This is not a command, but rather an indicator of the last item. | |
Enumerations | |
enum | lcb_SSLOPTS |
enum | lcb_RETRYMODEOPTS |
Select retry mode to manipulate. More... | |
enum | lcb_RETRYCMDOPTS |
enum | lcb_HTCONFIG_URLTYPE |
Enumeration representing various URL forms to use for the configuration stream. More... | |
Modes | |
Modes for the lcb_cntl() | |
#define | LCB_CNTL_SET |
Modify a setting. | |
#define | LCB_CNTL_GET |
Retrieve a setting. | |
Logging | |
Verbose logging may be enabled by default using the environment variable The maximum level is You may also install your own logger using lcb_cntl() and the LCB_CNTL_LOGGER constant. Note that the logger functions will not be called rapidly from within hot paths. | |
enum | lcb_log_severity_t |
Logging Levels. | |
typedef void(* | lcb_logging_callback) (struct lcb_logprocs_st *procs, unsigned int iid, const char *subsys, int severity, const char *srcfile, int srcline, const char *fmt, va_list ap) |
Logger callback. More... | |
#define | LCB_CNTL_LOGGER |
Access the lcb_logprocs structure. More... | |
struct lcb_cntl_vbinfo_t |
Structure containing mapping information for a key.
Data Fields | ||
---|---|---|
int | version | |
union lcb_cntl_vbinfo_t | v |
struct lcb_cntl_vbinfo_t.v.v0 |
struct lcb_logprocs |
Logging context.
This structure defines the logging handlers. Currently there is only a single field defined which is the default callback for the loggers. This API may change.
Data Fields | ||
---|---|---|
int | version | |
union lcb_logprocs | v |
#define LCB_CNTL_OP_TIMEOUT |
Operation Timeout.
The operation timeout is the maximum amount of time the library will wait for an operation to receive a response before invoking its callback with a failure status.
An operation may timeout if:
Modes | Arg |
---|---|
Get, Set | lcbU32* |
#define LCB_CNTL_VIEW_TIMEOUT |
Views Timeout This is the I/O timeout for HTTP requests issues with LCB_HTTP_TYPE_VIEWS.
Modes | Arg |
---|---|
Get, Set | lcb_U32* |
#define LCB_CNTL_N1QL_TIMEOUT |
N1QL Timeout This is the I/O timeout for N1QL queries, issued via lcb_n1ql_query()
Modes | Arg |
---|---|
Get, Set | lcb_U32* |
#define LCB_CNTL_BUCKETNAME |
Get the name of the bucket This returns the name of the bucket this instance is connected to, or NULL
if not yet connected to a bucket.
Modes | Arg |
---|---|
Get | const char* |
#define LCB_CNTL_HANDLETYPE |
Get the handle type.
This returns the handle type - which is either LCB_TYPE_CLUSTER or LCB_TYPE_BUCKET
Modes | Arg |
---|---|
Get | lcb_type_t* |
#define LCB_CNTL_VBCONFIG |
Get the vBucket handle.
Obtains the current cluster configuration from the client.
Modes | Arg |
---|---|
Get | lcbvb_CONFIG** |
#define LCB_CNTL_IOPS |
#define LCB_CNTL_VBMAP |
Get the vBucket ID for a given key, based on the current configuration.
Modes | Arg |
---|---|
Get | lcb_cntl_vbinfo_t* |
#define LCB_CNTL_CONFERRTHRESH |
Configuration error threshold.
This number indicates how many network/mapping/not-my-vbucket errors are received before a configuration update is requested again.
Modes | Arg |
---|---|
Get, Set | lcb_SIZE* |
#define LCB_CNTL_DURABILITY_TIMEOUT |
Default timeout for lcb_durability_poll()This is the time the client will spend sending repeated probes to a given key's vBucket masters and replicas before they are deemed not to have satisfied the durability requirements.
Modes | Arg |
---|---|
Get, Set | lcb_U32* |
#define LCB_CNTL_DURABILITY_INTERVAL |
Polling grace interval for lcb_durability_poll()
This is the time the client will wait between repeated probes to a given server.
Modes | Arg |
---|---|
Get, Set | lcb_U32* |
#define LCB_CNTL_HTTP_TIMEOUT |
#define LCB_CNTL_IOPS_DLOPEN_DEBUG |
Print verbose plugin load information to console.
This modifies a static, global setting regarding whether to print verbose information when trying to dynamically load an IO plugin. 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).
Modes | Arg |
---|---|
Get, Set | int* |
#define LCB_CNTL_CONFIGURATION_TIMEOUT |
Initial bootstrap timeout.
This is how long the client will wait to obtain the initial configuration.
Modes | Arg |
---|---|
Get, Set | lcb_U32* |
#define LCB_CNTL_RANDOMIZE_BOOTSTRAP_HOSTS |
Randomize order of bootstrap nodes.
This controls whether the connection attempts for configuration retrievals should be done in the supplied order or whether they should be randomized.
For the initial connection the supplied order is the list of hosts provided in the lcb_create_st structure. For subsequent connections this is the order of nodes as received by the server.
Modes | Arg |
---|---|
Get, Set | int* |
#define LCB_CNTL_CONFIG_CACHE_LOADED |
Determine if file-based configuration has been loaded.
If the configuration cache is in use, the argument pointer will be set to a true value. If the configuration cache was not used, the argument pointer will be set to false.
A false value may indicates that the client will need to load the configuration from the network. This may be caused by the following:
Modes | Arg |
---|---|
Get | int* |
#define LCB_CNTL_FORCE_SASL_MECH |
Force a specific SASL mechanism.
Force a specific SASL mechanism to use for authentication. This can allow a user to ensure a certain level of security and have the connection fail if the desired mechanism is not available.
When setting this value, the arg parameter shall be a NUL
-terminated string or a NULL
pointer (to unset). When retrieving this value, the parameter shall be set to a char **
. Note that this value (in LCB_CNTL_GET) is valid only until the next call to a libcouchbase API, after which it may have been freed.
Modes | Arg |
---|---|
Get | char** |
Set | char* |
#define LCB_CNTL_MAX_REDIRECTS |
Maximum number of HTTP redirects to follow Set how many redirects the library should follow for the single request.
Set to -1 to remove limit at all.
Modes | Arg |
---|---|
Get, Set | int* |
#define LCB_CNTL_LOGGER |
Access the lcb_logprocs structure.
The lcb_logoprocs structure passed must not be freed until the instance is completely destroyed. This will only happen once the destruction callback is called (see lcb_set_destroy_callback()).
Modes | Arg |
---|---|
Get | lcb_logprocs** |
Set | lcb_logprocs* |
#define LCB_CNTL_CONFDELAY_THRESH |
Refresh Throttling.
Modify the amount of time (in microseconds) before the LCB_CNTL_CONFERRTHRESH will forcefully be set to its maximum number forcing a configuration refresh.
Note that if you expect a high number of timeouts in your operations, you should set this to a high number (along with CONFERRTHRESH
). If you are using the default timeout setting, then this value is likely optimal.
Modes | Arg |
---|---|
Get, Set | lcb_U32* |
#define LCB_CNTL_CONFIG_TRANSPORT |
Get the transport used to fetch cluster configuration.
Modes | Arg |
---|---|
Get | lcb_config_transport_t* |
#define LCB_CNTL_CONFIG_NODE_TIMEOUT |
Per-node configuration timeout.
The per-node configuration timeout sets the amount of time to wait for each node within the bootstrap/configuration process. This interval is a subset of the LCB_CNTL_CONFIGURATION_TIMEOUT option mentioned above and is intended to ensure that the bootstrap process does not wait too long for a given node. Nodes that are physically offline may never respond and it may take a long time until they are detected as being offline. See CCBC-261 and CCBC-313 for more reasons.
CONFIGURATION_TIMEOUT
should be higher than this number. No check is made to ensure that this is the case, however.Modes | Arg |
---|---|
Get, Set | lcb_U32* |
#define LCB_CNTL_HTCONFIG_IDLE_TIMEOUT |
Idling/Persistence for HTTP bootstrap.
By default the behavior of the library for HTTP bootstrap is to keep the stream open at all times (opening a new stream on a different host if the existing one is broken) in order to proactively receive configuration updates.
The default value for this setting is -1. Changing this to another number invokes the following semantics:
Modes | Arg |
---|---|
Get, Set | lcb_U32* |
#define LCB_CNTL_CHANGESET |
Get the current SCM changeset for the library binary.
Modes | Arg |
---|---|
Get | char** |
#define LCB_CNTL_CONFIGCACHE |
file used for the configuration cache.
The configuration cache allows to bootstrap from a cluster without using the initial bootstrap connection, considerably reducing latency. If the file passed does not exist, the normal bootstrap process is performed and the file is written to with the current information.
Modes | Arg |
---|---|
Get | char** |
Set | char* |
#define LCB_CNTL_CONFIGCACHE_RO |
File used for read-only configuration cache.
This is identical to the LCB_CNTL_CONFIGCACHE directive, except that it guarantees that the library will never overwrite or otherwise modify the path specified.
#define LCB_CNTL_SSL_MODE |
Get SSL Mode.
Retrieve the SSL mode currently in use by the library. This is a read-only setting. To set the SSL mode at the library, specify the appropriate values within the connection string. See lcb_create_st3 for details.
Modes | Arg |
---|---|
Get | int* (value is one of lcb_SSLOPTS) |
#define LCB_CNTL_SSL_CERT |
Get SSL Certificate path.
Retrieve the path to the CA certificate (if any) being used.
Modes | Arg |
---|---|
Get | char** |
#define LCB_RETRYOPT_CREATE | ( | mode, | |
policy | |||
) |
Create a retry setting value.
mode | the mode to set ( |
policy | the policy determining which commands should be retried ( |
lcb_U32
and passed to the LCB_CNTL_RETRYMODE setting #define LCB_CNTL_RETRYMODE |
Set retry policies.
This function sets the retry behavior. The retry behavior is the action the library should take when a command has failed because of a failure which may be a result of environmental and/or topology issues. In such cases it may be possible to retry the command internally and have it succeed a second time without propagating an error back to the application.
The behavior consists of a mode and command selectors. The command selector indicates which commands should be retried (and which should be propagated up to the user) whereas the mode indicates under which circumstances should the command policy be used.
Disable retries anywhere:
Only retry simple GET operations when retry is needed because of topology changes:
Determine the behavior of the library when a NOT_MY_VBUCKET
is received:
Modes | Arg |
---|---|
Get, Set | lcb_U32 * |
#define LCB_CNTL_HTCONFIG_URLTYPE |
Set the URL selection mode.
The URL type can be a mask of the lcb_HTCONFIG_URLTYPE constants which indicate which URLs the HTTP provider should use.
The default is to use the 25PLUS
URI first, and fallback on the compat uri if the terse one fails with an HTTP 404 (Not Found). The new-style URI is considered more efficient on cluster resources and can help the cluster maintain many more streaming connections than the compat version, however it is only available in Couchbase Server 2.5 and greater.
This setting is only used when CCCP is disabled. This will typically be for older clusters or for memcached buckets.
Modes | Arg |
---|---|
Get, Set | int* (value is one of lcb_HTCONFIG_URLTYPE) |
#define LCB_CNTL_SYNCDESTROY |
Modes | Arg |
---|---|
Get, Set | int* (as a boolean) |
#define LCB_CNTL_CONLOGGER_LEVEL |
Sets the logging level for the console logger. If a logger is already initialized (either from the environment, or via lcb_cntl_logger() then this operation does nothing.
This is mainly useful for applications which want to proxy the built in logging options via command line options and the like, rather than setting it from the environment.
The argument passed to lcb_cntl() is an integer of 0 until LCB_LOGLEVEL_MAX
, though the actual type is of lcb_U32
rather than an enum type.
Modes | Arg |
---|---|
Set | const lcb_U32 * |
#define LCB_CNTL_CONLOGGER_FP |
Sets the output file (as a FILE*
) for the console logger. Note that any existing file pointer will be cleared (but not fclose()
d.
If used with lcb_cntl_string(), (using the console_log_file
parameter), the third argument is taken as the name of a file. Note that the user is responsible for closing the file.
This setting does not require a library handle and therefore the first argument to lcb_cntl() should be NULL
.
Modes | Arg |
---|---|
Get | FILE** |
Set | FILE* |
#define LCB_CNTL_DETAILED_ERRCODES |
Sets the behavior for reporting network errors. By default network errors are returned as LCB_NETWORK_ERROR
return codes for compatibility reasons. More detailed error codes may be available by enabling this option which will return appropriate error codes which have a category of LCB_ERRTYPE_NETWORK
Using this option means your programming model is centered around the various LCB_EIF* macros (see <libcouchbase/error.h>) rather than individual codes.
Modes | Arg |
---|---|
Get, Set | int * (As a boolean) |
#define LCB_CNTL_RETRY_INTERVAL |
Sets the interval at which the retry queue will attempt to resend a failed operation. When an operation fails and the retry policy (see LCB_CNTL_RETRYMODE) allows the operation to be retried, it shall be placed into a queue, and then be retried within a given interval.
Setting a high value will be friendlier on the network but also potentially increase latency, while setting this to a low value may cause unnecessary network traffic for operations which are not yet ready to be retried.
Modes | Arg |
---|---|
Get, Set | lcb_U32* (microseconds) |
#define LCB_CNTL_RETRY_BACKOFF |
When an operation has been retried more than once and it has still not succeeded, the library will attempt to back off for the operation by scheduling it to be retried in LCB_CNTL_RETRY_INTEVAL * ${n}
microseconds, where ${n}
is the factor controlled by this setting.
Modes | Arg |
---|---|
Get, Set | float* |
#define LCB_CNTL_RETRY_NMV_IMM |
Since version 2.4.8, packets by default are retried immediately on a different node if it had previously failed with a not-my-vbucket response, and is thus not subject to the LCB_CNTL_RETRY_INTERVAL and LCB_CNTL_RETRY_BACKOFF settings. Disabling this setting will restore the older behavior. This may be used in case there are problems with the default heuristic/retry algorithm.
#define LCB_CNTL_HTTP_POOLSIZE |
Set the maximum pool size for pooled http (view request) sockets. This should be set to 1 (the default) unless you plan to execute concurrent view requests. You may set this to 0 to disable pooling
Modes | Arg |
---|---|
Get, Set | lcb_SIZE |
#define LCB_CNTL_HTTP_REFRESH_CONFIG_ON_ERROR |
uncommitted Determine whether or not a new configuration should be received when an error is received over the HTTP API (i.e.
via lcb_make_http_request().
The default value is true, however you may wish to disable this if you are expectedly issuing a lot of requests which may result in an error.
Modes | Arg |
---|---|
Get, Set | int (as boolean) |
#define LCB_CNTL_SCHED_IMPLICIT_FLUSH |
Modes | Arg |
---|---|
Get, Set | int (as boolean) |
#define LCB_CNTL_FETCH_MUTATION_TOKENS |
Allow the server to return an additional 16 bytes of data for each mutation operation. This extra information may help with more reliable durability polling, but will also increase the size of the response packet.
This should be set on the instance before issuing lcb_connect(). While this may also be set after lcb_connect() is called, it will currently only take effect when a server reconnects (which itself may be undefined).
Modes | Arg |
---|---|
Get, Set | int (as boolean) |
#define LCB_CNTL_DURABILITY_MUTATION_TOKENS |
This setting determines whether the lcb_durability_poll() function will transparently attempt to use mutation token functionality (rather than checking the CAS). This option is most useful for older code which does explicitly use mutation tokens but would like to use its benefits when ensuring durability constraints are satisfied.
This option is enabled by default. Users may wish to disable this if they are performing durability operations against items stored from different client instances, as this will make use of a client-global state which is derived on a per-vBucket basis. This means that the last mutation performed on a given vBucket for the client will be used, which in some cases may be older or newer than the mutations passed to the lcb_durability_poll() function.
Modes | Arg |
---|---|
Get, Set | int (as boolean) |
#define LCB_CNTL_MUTATION_TOKENS_SUPPORTED |
This read-only property determines if the mutation token mechanism is supported on the cluster itself. This will only be accurate once a single operation has been performed on the cluster - or in other words, once a connection to a data node has been established for the purposes of normal operations.
Modes | Arg |
---|---|
Get | int (as boolean) |
#define LCB_CNTL_RESET_TIMEOUT_ON_WAIT |
Modes | Arg |
---|---|
Get, Set | int (as boolean) |
"readj_wait_tmo"
for the string version #define LCB_CNTL_N1QL_CLEARACHE |
This does not take any arguments, and is valid only on LCB_CNTL_SET
typedef void(* lcb_logging_callback) (struct lcb_logprocs_st *procs, unsigned int iid, const char *subsys, int severity, const char *srcfile, int srcline, const char *fmt, va_list ap) |
Logger callback.
This callback is invoked for each logging message emitted
procs | the logging structure provided |
iid | instance id |
subsys | a string describing the module which emitted the message |
severity | one of the LCB_LOG_* severity constants. |
srcfile | the source file which emitted this message |
srcline | the line of the file for the message |
fmt | a printf format string |
ap | a va_list for vprintf |
enum lcb_SSLOPTS |
enum lcb_RETRYMODEOPTS |
Select retry mode to manipulate.
enum lcb_RETRYCMDOPTS |
enum lcb_HTCONFIG_URLTYPE |
Enumeration representing various URL forms to use for the configuration stream.