Couchbase C Client  2.9.5
Asynchronous C Client for Couchbase
couchbase.h File Reference

Main header file for Couchbase. More...

#include <stddef.h>
#include <time.h>
#include <stdarg.h>
#include <stdio.h>
#include <libcouchbase/sysdefs.h>
#include <libcouchbase/assert.h>
#include <libcouchbase/visibility.h>
#include <libcouchbase/error.h>
#include <libcouchbase/iops.h>
#include <libcouchbase/http.h>
#include <libcouchbase/configuration.h>
#include <libcouchbase/kvbuf.h>
#include <libcouchbase/auth.h>
#include <libcouchbase/tracing.h>
#include <libcouchbase/_cxxwrap.h>
#include <libcouchbase/cntl.h>
#include <libcouchbase/subdoc.h>
#include <libcouchbase/deprecated.h>
#include <libcouchbase/api-legacy.h>

Go to the source code of this file.

Data Structures

struct  lcb_create_st3
 Inner structure V3 for lcb_create(). More...
 
struct  lcb_create_st4
 Inner structure V4 for lcb_create(). More...
 
struct  lcb_create_st
 Wrapper structure for lcb_create() More...
 
union  lcb_create_st::lcb_CRST_u
 This union contains the set of current and historical options. More...
 
struct  lcb_CMDBASE
 Common ABI header for all commands. More...
 
struct  lcb_RESPBASE
 Base response structure for callbacks. More...
 
struct  lcb_RESPSERVERBASE
 Base structure for informational commands from servers This contains an additional lcb_RESPSERVERBASE::server field containing the server which emitted this response. More...
 
struct  lcb_MUTATION_TOKEN
 Structure representing a synchronization token. More...
 
struct  lcb_CMDGET
 Command for retrieving a single item. More...
 
struct  lcb_RESPGET
 Response structure when retrieving a single item. More...
 
struct  lcb_CMDGETREPLICA
 Command for requesting an item from a replica. More...
 
struct  lcb_CMDSTORE
 Command for storing an item to the server. More...
 
struct  lcb_RESPSTORE
 Response structure for lcb_store3() More...
 
struct  lcb_MULTICMD_CTX
 Multi Command Context API Some commands (notably, OBSERVE and its higher level equivalent, endue) are handled more efficiently at the cluster side by stuffing multiple items into a single packet. More...
 
struct  lcb_DURABILITYOPTSv0
 Options for lcb_endure3_ctxnew() More...
 
struct  lcb_durability_opts_t
 Options for lcb_endure3_ctxnew() (wrapper) More...
 
struct  lcb_CMDENDURE
 Command structure for endure. More...
 
struct  lcb_RESPENDURE
 Response structure for endure. More...
 
struct  lcb_CMDSTOREDUR
 Command structure for lcb_storedur3() This is much like lcb_CMDSTORE, but also includes durability options. More...
 
struct  lcb_RESPSTOREDUR
 Response structure for `LCB_CALLBACK_STOREDUR. More...
 
struct  lcb_CMDOBSERVE
 Structure for an observe request. More...
 
struct  lcb_RESPOBSERVE
 Response structure for an observe command. More...
 
struct  lcb_CMDOBSEQNO
 Command structure for lcb_observe_seqno3(). More...
 
struct  lcb_RESPOBSEQNO
 Response structure for lcb_observe_seqno3() More...
 
struct  lcb_CMDCOUNTER
 Command for counter operations. More...
 
struct  lcb_RESPCOUNTER
 Response structure for counter operations. More...
 
struct  lcb_RESPSTATS
 Response structure for cluster statistics. More...
 
struct  lcb_RESPMCVERSION
 Response structure for the version command. More...
 
struct  lcb_CMDPING
 
Structure for PING requests. More...
 
struct  lcb_PINGSVC
 
Entry describing the status of the service in the cluster. More...
 
struct  lcb_RESPPING
 
Structure for PING responses. More...
 
struct  lcb_CMDHTTP
 Structure for performing an HTTP request. More...
 
struct  lcb_RESPHTTP
 Structure for HTTP responses. More...
 

Macros

#define LCB_CONFIG_MCD_PORT
 
#define LCB_CONFIG_MCD_SSL_PORT
 
#define LCB_CONFIG_HTTP_PORT
 
#define LCB_CONFIG_HTTP_SSL_PORT
 
#define LCB_CONFIG_MCCOMPAT_PORT
 
#define LCB_CMDGET_F_CLEAREXP
 If this bit is set in lcb_CMDGET::cmdflags then the expiry time is cleared if lcb_CMDGET::exptime is 0. More...
 
#define LCB_CMD_SET_VALUE(scmd, valbuf, vallen)
 
Set the value buffer for the command. This may be used when the new value is a single contiguous buffer. More...
 
#define LCB_CMD_SET_VALUEIOV(scmd, iovs, niovs)
 
Set value from a series of input buffers. This may be used when the input buffer is not contiguous. Using this call eliminates the need for creating a temporary contiguous buffer in which to store the value. More...
 
#define LCB_MUTATION_TOKEN_ID(p)
 Get the vBucket UUID.
 
#define LCB_MUTATION_TOKEN_SEQ(p)
 Get the sequence number.
 
#define LCB_MUTATION_TOKEN_VB(p)
 Get the vBucket number itself.
 
#define LCB_MUTATION_TOKEN_ISVALID(p)
 Whether this mutation token has valid contents.
 
#define LCB_PINGSVC_F_KV
 Ping data (Key/Value) service. More...
 
#define LCB_PINGSVC_F_N1QL
 Ping query (N1QL) service. More...
 
#define LCB_PINGSVC_F_VIEWS
 Ping views (Map/Reduce) service. More...
 
#define LCB_PINGSVC_F_FTS
 Ping full text search (FTS) service. More...
 
#define LCB_PINGOPT_F_NOMETRICS
 Do not record any metrics or status codes from ping responses. More...
 
#define LCB_PINGOPT_F_JSON
 Automatically encode PING result as JSON. More...
 
#define LCB_PINGOPT_F_JSONDETAILS
 Add extra details about service status into generated JSON. More...
 
#define LCB_PINGOPT_F_JSONPRETTY
 Generate indented JSON, which is better for reading. More...
 
#define LCB_CMDHTTP_F_STREAM
 Command flag for HTTP to indicate that the callback is to be invoked multiple times for each new chunk of incoming data. More...
 
#define LCB_CMDHTTP_F_CASTMO
 
More...
 
#define LCB_CMDHTTP_F_NOUPASS
 
More...
 
#define LCB_DATATYPE_JSON
 
#define LCB_GETNODE_UNAVAILABLE
 String constant returned by lcb_get_node() when the LCB_NODE_NEVERNULL flag is specified, and no node can be returned.
 
#define LCB_VERSION_STRING
 libcouchbase version string
 
#define LCB_VERSION
 libcouchbase hex version More...
 
#define LCB_VERSION_CHANGESET
 The SCM revision ID. More...
 
#define LCB_SUPPORTS_SSL
 Whether the library has SSL support.
 
#define LCB_SUPPORTS_SNAPPY
 Whether the library has experimental compression support.
 
#define LCB_SUPPORTS_TRACING
 Whether the library has experimental tracing support.
 
Creating Commands

Issuing a command to the Cluster involves selecting the correct command structure, populating it with the data relevant for the command, optionally associating the command with your own application data, issuing the command to a spooling function, and finally receiving the response.

Command structures all derive from the common lcb_CMDBASE structure. This structure defines the common fields for all commands.

Almost all commands need to contain a key, which should be assigned using the LCB_CMD_SET_KEY() macro.

#define LCB_CMD_BASE
 
#define LCB_CMD_F_INTERNAL_CALLBACK
 
Flag for lcb_CMDBASE::cmdflags which indicates that the lcb_CMDBASE::cookie is a special callback object. More...
 
#define LCB_CMD_F_MULTIAUTH
 If this flag is set, then multiple authentication credentials will be passed to the server. More...
 
#define LCB_CMD_SET_KEY(cmd, keybuf, keylen)
 Set the key for the command. More...
 
#define LCB_CMD__SETVBID(cmd, vbid)
 
Sets the vBucket ID for the item. More...
 

Typedefs

typedef struct lcb_st * lcb_t
 Library handle representing a connection to a cluster and its data buckets. More...
 
typedef struct lcb_http_request_st * lcb_http_request_t
 
typedef lcb_U8 lcb_datatype_t
 
typedef lcb_U32 lcb_USECS
 
typedef void(* lcb_bootstrap_callback) (lcb_t instance, lcb_error_t err)
 
Bootstrap callback. More...
 
typedef lcb_CMDBASE lcb_CMDREMOVE
 Command for removing an item from the server. More...
 
typedef lcb_RESPBASE lcb_RESPREMOVE
 Response structure for removal operation. More...
 
typedef lcb_CMDBASE lcb_CMDUNLOCK
 Command for lcb_unlock3() More...
 
typedef lcb_RESPBASE lcb_RESPUNLOCK
 Response structure for an unlock command. More...
 
typedef lcb_CMDBASE lcb_CMDTOUCH
 Command structure for a touch request. More...
 
typedef lcb_RESPBASE lcb_RESPTOUCH
 Response structure for a touch request. More...
 
typedef lcb_CMDBASE lcb_CMDCBFLUSH
 
typedef lcb_RESPBASE lcb_RESPCBFLUSH
 
typedef lcb_CMDBASE lcb_CMDFLUSH
 
typedef lcb_RESPSERVERBASE lcb_RESPFLUSH
 
typedef lcb_CMDBASE lcb_CMDNOOP
 
typedef lcb_RESPSERVERBASE lcb_RESPNOOP
 
typedef void(* lcb_destroy_callback) (const void *cookie)
 Callback received when instance is about to be destroyed. More...
 
typedef enum lcb_timeunit_t lcb_timeunit_t
 
typedef void(* lcb_timings_callback) (lcb_t instance, const void *cookie, lcb_timeunit_t timeunit, lcb_U32 min, lcb_U32 max, lcb_U32 total, lcb_U32 maxtotal)
 The following function is called for each bucket in the timings histogram when you call lcb_get_timings. More...
 
typedef struct lcb_histogram_st lcb_HISTOGRAM
 
typedef void(* lcb_HISTOGRAM_CALLBACK) (const void *cookie, lcb_timeunit_t timeunit, lcb_U32 min, lcb_U32 max, lcb_U32 total, lcb_U32 maxtotal)
 

Enumerations

enum  lcb_type_t
 Handle types. More...
 
enum  lcb_BTYPE
 Type of the bucket. More...
 
enum  lcb_replica_t
 Select get-replica mode. More...
 
enum  lcb_storage_t
 Values for lcb_CMDSTORE::operation. More...
 
enum  lcb_PINGSVCTYPE
 
Type of the service. More...
 
enum  lcb_PINGSTATUS
 
Status of the service More...
 
enum  lcb_http_type_t
 The type of HTTP request to execute. More...
 
enum  lcb_http_method_t
 HTTP Request method enumeration These just enumerate the various types of HTTP request methods supported. More...
 
enum  lcb_WAITFLAGS
 Flags for lcb_wait3() More...
 
enum  lcb_VALUEFLAGS
 
enum  lcb_GETNODETYPE
 Type of node to retrieve for the lcb_get_node() function. More...
 
enum  lcb_timeunit_t
 Time units reported by lcb_get_timings() More...
 
enum  lcb_DUMPFLAGS
 

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...
 
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_set_auth (lcb_t instance, lcb_AUTHENTICATOR *auth)
 Sets the authenticator object for the instance. More...
 
lcb_error_t lcb_get3 (lcb_t instance, const void *cookie, const lcb_CMDGET *cmd)
 
Spool a single get operation More...
 
lcb_error_t lcb_rget3 (lcb_t instance, const void *cookie, const lcb_CMDGETREPLICA *cmd)
 Spool a single get-with-replica request. More...
 
lcb_error_t lcb_store3 (lcb_t instance, const void *cookie, const lcb_CMDSTORE *cmd)
 
Schedule a single storage request More...
 
lcb_error_t lcb_remove3 (lcb_t instance, const void *cookie, const lcb_CMDREMOVE *cmd)
 Spool a removal of an item. More...
 
const lcb_MUTATION_TOKENlcb_resp_get_mutation_token (int cbtype, const lcb_RESPBASE *rb)
 Retrieves the mutation token from the response structure. More...
 
const lcb_MUTATION_TOKENlcb_get_mutation_token (lcb_t instance, const lcb_KEYBUF *kb, lcb_error_t *errp)
 
More...
 
lcb_error_t lcb_counter3 (lcb_t instance, const void *cookie, const lcb_CMDCOUNTER *cmd)
 Schedule single counter operation. More...
 
lcb_error_t lcb_unlock3 (lcb_t instance, const void *cookie, const lcb_CMDUNLOCK *cmd)
 
Unlock a previously locked item using lcb_CMDGET::lock More...
 
lcb_error_t lcb_touch3 (lcb_t instance, const void *cookie, const lcb_CMDTOUCH *cmd)
 Spool a touch request. More...
 
lcb_error_t lcb_cbflush3 (lcb_t instance, const void *cookie, const lcb_CMDCBFLUSH *cmd)
 
More...
 
lcb_error_t lcb_flush3 (lcb_t instance, const void *cookie, const lcb_CMDFLUSH *cmd)
 
More...
 
lcb_error_t lcb_noop3 (lcb_t instance, const void *cookie, const lcb_CMDNOOP *cmd)
 
More...
 
lcb_error_t lcb_ping3 (lcb_t instance, const void *cookie, const lcb_CMDPING *cmd)
 
Check connections by sending NOOP-like messages to all services. More...
 
lcb_error_t lcb_diag (lcb_t instance, const void *cookie, const lcb_CMDDIAG *cmd)
 
Returns diagnostics report about network connections. More...
 
lcb_error_t lcb_http3 (lcb_t instance, const void *cookie, const lcb_CMDHTTP *cmd)
 
More...
 
void lcb_cancel_http_request (lcb_t instance, lcb_http_request_t request)
 
Cancel ongoing HTTP request 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...
 
lcb_error_t lcb_tick_nowait (lcb_t instance)
 
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...
 
int lcb_is_waiting (lcb_t instance)
 
Check if instance is blocked in the event loop More...
 
void lcb_refresh_config (lcb_t instance)
 
Force the library to refetch the cluster configuration More...
 
void lcb_sched_enter (lcb_t instance)
 
Enter a scheduling context. More...
 
void lcb_sched_leave (lcb_t instance)
 
Leave the current scheduling context, scheduling the commands within the context to be flushed to the network. More...
 
void lcb_sched_fail (lcb_t instance)
 
Fail all commands in the current scheduling context. More...
 
void lcb_sched_flush (lcb_t instance)
 
Request commands to be flushed to the network More...
 
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...
 
const char * lcb_get_node (lcb_t instance, lcb_GETNODETYPE type, unsigned index)
 
Return a string of host:port for a node of the given type. More...
 
const char * lcb_get_keynode (lcb_t instance, const void *key, size_t nkey)
 
Get the target server for a given key. More...
 
lcb_S32 lcb_get_num_replicas (lcb_t instance)
 
Get the number of the replicas in the cluster More...
 
lcb_S32 lcb_get_num_nodes (lcb_t instance)
 
Get the number of the nodes in the cluster More...
 
const char *const * lcb_get_server_list (lcb_t instance)
 
Get a list of nodes in the cluster More...
 
void lcb_dump (lcb_t instance, FILE *fp, lcb_U32 flags)
 
Write a textual dump to a file. More...
 
lcb_error_t lcb_cntl (lcb_t instance, int mode, int cmd, void *arg)
 
This function exposes an ioctl/fcntl-like interface to read and write various configuration properties to and from an lcb_t handle. More...
 
lcb_error_t lcb_cntl_string (lcb_t instance, const char *key, const char *value)
 
Alternatively one may change configuration settings by passing a string key and value. More...
 
lcb_error_t lcb_cntl_setu32 (lcb_t instance, int cmd, lcb_U32 arg)
 
Convenience function to set a value as an lcb_U32 More...
 
lcb_U32 lcb_cntl_getu32 (lcb_t instance, int cmd)
 
Retrieve an lcb_U32 setting More...
 
int lcb_cntl_exists (int ctl)
 Determine if a specific control code exists. More...
 
lcb_error_t lcb_enable_timings (lcb_t instance)
 
Start recording timing metrics for the different operations. More...
 
lcb_error_t lcb_disable_timings (lcb_t instance)
 
Stop recording (and release all resources from previous measurements) timing metrics. More...
 
lcb_error_t lcb_get_timings (lcb_t instance, const void *cookie, lcb_timings_callback callback)
 
Get the timings histogram More...
 
const char * lcb_get_version (lcb_U32 *version)
 Get the version of the library. More...
 
int lcb_supports_feature (int n)
 
More...
 
void * lcb_mem_alloc (lcb_SIZE size)
 Functions to allocate and free memory related to libcouchbase. More...
 
void lcb_mem_free (void *ptr)
 Use this to free memory allocated with lcb_mem_alloc.
 
LCB_INTERNAL_API void lcb_run_loop (lcb_t instance)
 
More...
 
LCB_INTERNAL_API void lcb_stop_loop (lcb_t instance)
 
LCB_INTERNAL_API lcb_U64 lcb_nstime (void)
 
lcb_HISTOGRAM * lcb_histogram_create (void)
 
More...
 
void lcb_histogram_destroy (lcb_HISTOGRAM *hg)
 
More...
 
void lcb_histogram_record (lcb_HISTOGRAM *hg, lcb_U64 duration)
 
More...
 
void lcb_histogram_read (const lcb_HISTOGRAM *hg, const void *cookie, lcb_HISTOGRAM_CALLBACK cb)
 
More...
 
void lcb_histogram_print (lcb_HISTOGRAM *hg, FILE *stream)
 Print the histogram to the specified FILE. More...
 
const char * lcb_resp_get_error_context (int cbtype, const lcb_RESPBASE *rb)
 
More...
 
const char * lcb_resp_get_error_ref (int cbtype, const lcb_RESPBASE *rb)
 
More...
 
int lcb_is_redacting_logs (lcb_t instance)
 
More...
 
Server Versions
Warning
This does not return the actual Couchbase version but rather the internal version of the memcached server.
lcb_error_t lcb_server_versions3 (lcb_t instance, const void *cookie, const lcb_CMDBASE *cmd)
 
More...
 

Variables

LCB_EXTERN_VAR const lcb_U32 lcb_version_g
 Global/extern variable containing the version of the library.
 

Receiving Responses

This section describes the APIs used in receiving responses.

Each command will have a callback invoked (typically once, for some commands this may be more than once) with a response structure. The response structure will be of a type that extends lcb_RESPBASE. The response structure should not be modified and any of its fields should be considered to point to memory which will be released after the callback exits.

The common response header contains the lcb_RESPBASE::cookie field which is the pointer to your application context (passed as the second argument to the spooling function) and allows you to associate a specific command with a specific response.

The header will also contain the key (lcb_RESPBASE::key) field which can also help identify the specific command. This is useful if you maintain a single cookie for multiple commands, and have per-item specific data you wish to associate within the cookie itself.

Success or failure of the operation is signalled through the lcb_RESPBASE::rc field. Note that even in the case of failure, the lcb_RESPBASE::cookie and lcb_RESPBASE::key fields will always be populated.

Most commands also return the CAS of the item (as it exists on the server) and this is placed inside the lcb_RESPBASE::cas field, however it is only valid in the case where lcb_RESPBASE::rc is LCB_SUCCESS.

#define LCB_RESP_BASE
 
#define LCB_RESP_SERVER_FIELDS
 
#define LCB_CALLBACK_VIEWQUERY
 Callback type for views (cannot be used for lcb_install_callback3())
 
#define LCB_CALLBACK_N1QL
 Callback type for N1QL (cannot be used for lcb_install_callback3())
 
#define LCB_CALLBACK_IXMGMT
 Callback type for N1QL index management (cannot be used for lcb_install_callback3())
 
enum  lcb_RESPFLAGS
 Response flags. More...
 
enum  lcb_CALLBACKTYPE
 The type of response passed to the callback. More...
 
typedef void(* lcb_RESPCALLBACK) (lcb_t instance, int cbtype, const lcb_RESPBASE *resp)
 Callback invoked for responses. More...
 
lcb_RESPCALLBACK lcb_install_callback3 (lcb_t instance, int cbtype, lcb_RESPCALLBACK cb)
 
More...
 
lcb_RESPCALLBACK lcb_get_callback3 (lcb_t instance, int cbtype)
 
More...
 
const char * lcb_strcbtype (int cbtype)
 Returns the type of the callback as a string. More...
 

Wait for a mutation to be persisted/replicated

#define LCB_CMDENDURE_F_MUTATION_TOKEN
 Must specify this flag if using the 'mutation_token' field, as it was added in a later version.
 
#define LCB_DURABILITY_VALIDATE_CAPMAX
 
enum  lcb_DURMODE
 Type of durability polling to use. More...
 
lcb_MULTICMD_CTXlcb_endure3_ctxnew (lcb_t instance, const lcb_durability_opts_t *options, lcb_error_t *err)
 
Return a new command context for scheduling endure operations More...
 
lcb_error_t lcb_storedur3 (lcb_t instance, const void *cookie, const lcb_CMDSTOREDUR *cmd)
 
More...
 
lcb_error_t lcb_durability_validate (lcb_t instance, lcb_U16 *persist_to, lcb_U16 *replicate_to, int options)
 
More...
 

Retrieve current persistence/replication status

#define LCB_CMDOBSERVE_F_MASTER_ONLY
 Set this bit in the cmdflags field to indicate that only the master node should be contacted.
 
enum  lcb_observe_t
 Possible statuses for keys in OBSERVE response. More...
 
lcb_MULTICMD_CTXlcb_observe3_ctxnew (lcb_t instance)
 
Create a new multi context for an observe operation More...
 
lcb_error_t lcb_observe_seqno3 (lcb_t instance, const void *cookie, const lcb_CMDOBSEQNO *cmd)
 
Get the persistence/replication status for a given mutation token More...
 

Server Statistics

#define LCB_CMDSTATS_F_KV
 The key is a stored item for which statistics should be retrieved. More...
 
typedef lcb_CMDBASE lcb_CMDSTATS
 Command structure for stats request The lcb_CMDSTATS::key field should contain the statistics key, or be empty if the default statistics are desired. More...
 
lcb_error_t lcb_stats3 (lcb_t instance, const void *cookie, const lcb_CMDSTATS *cmd)
 Schedule a request for statistics from the cluster. More...
 

Server Log Verbosity

enum  lcb_verbosity_level_t
 level field for lcb_server_verbosity3 ()
 
typedef lcb_RESPSERVERBASE lcb_RESPVERBOSITY
 
lcb_error_t lcb_server_verbosity3 (lcb_t instance, const void *cookie, const lcb_CMDVERBOSITY *cmd)
 

Detailed Description

Main header file for Couchbase.


Data Structure Documentation

◆ lcb_create_st::lcb_CRST_u

union lcb_create_st::lcb_CRST_u

This union contains the set of current and historical options.

The The v3 field should be used.

Data Fields
struct lcb_create_st0 v0
struct lcb_create_st1 v1
struct lcb_create_st2 v2
struct lcb_create_st3 v3 Use this field.
struct lcb_create_st4 v4

Macro Definition Documentation

◆ LCB_DATATYPE_JSON

#define LCB_DATATYPE_JSON

Enumeration Type Documentation

◆ lcb_VALUEFLAGS

Stability
Internal:

◆ lcb_DUMPFLAGS

Enumerator
LCB_DUMP_VBCONFIG 

Dump the raw vbucket configuration.

LCB_DUMP_PKTINFO 

Dump information about each packet.

LCB_DUMP_BUFINFO 

Dump memory usage/reservation information about buffers.

LCB_DUMP_METRICS 

Dump various metrics information.

LCB_DUMP_ALL 

Dump everything.

Function Documentation

◆ lcb_refresh_config()

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_mem_alloc()

void* lcb_mem_alloc ( lcb_SIZE  size)

Functions to allocate and free memory related to libcouchbase.

This is mainly for use on Windows where it is possible that the DLL and EXE are using two different CRTs

◆ lcb_run_loop()

LCB_INTERNAL_API void lcb_run_loop ( lcb_t  instance)


Stability
Internal:

These two functions unconditionally start and stop the event loop. These should be used only when necessary. Use lcb_wait and lcb_breakout for safer variants.

Internally these proxy to the run_event_loop/stop_event_loop calls

◆ lcb_stop_loop()

LCB_INTERNAL_API void lcb_stop_loop ( lcb_t  instance)
Stability
Internal:

◆ lcb_nstime()

LCB_INTERNAL_API lcb_U64 lcb_nstime ( void  )
Stability
Internal:

◆ lcb_histogram_create()

lcb_HISTOGRAM* lcb_histogram_create ( void  )


Stability
Volatile:
Create a histogram structure
Returns
a new histogram structure

◆ lcb_histogram_destroy()

void lcb_histogram_destroy ( lcb_HISTOGRAM *  hg)


Stability
Volatile:
free a histogram structure
Parameters
hgthe histogram

◆ lcb_histogram_record()

void lcb_histogram_record ( lcb_HISTOGRAM *  hg,
lcb_U64  duration 
)


Stability
Volatile:
Add an entry to a histogram structure
Parameters
hgthe histogram
durationthe duration in nanoseconds

◆ lcb_histogram_read()

void lcb_histogram_read ( const lcb_HISTOGRAM *  hg,
const void *  cookie,
lcb_HISTOGRAM_CALLBACK  cb 
)


Stability
Volatile:
Repeatedly invoke a callback for all entries in the histogram
Parameters
hgthe histogram
cookiepointer passed to callback
cbcallback to invoke

◆ lcb_histogram_print()

void lcb_histogram_print ( lcb_HISTOGRAM *  hg,
FILE *  stream 
)

Print the histogram to the specified FILE.

This essentially outputs the same raw information as lcb_histogram_read(), except it prints in implementation-defined format. It's simpler to use than lcb_histogram_read, but less flexible.

Parameters
hgthe histogram
streamFile to print the histogram to.

◆ lcb_resp_get_error_context()

const char* lcb_resp_get_error_context ( int  cbtype,
const lcb_RESPBASE rb 
)


Stability
Volatile:

Retrieves the extra error context from the response structure.

This context does not duplicate information described by status code rendered by lcb_strerror() function, and should be logged if available.

Returns
the pointer to string or NULL if context wasn't specified.

◆ lcb_resp_get_error_ref()

const char* lcb_resp_get_error_ref ( int  cbtype,
const lcb_RESPBASE rb 
)


Stability
Uncommitted:

Retrieves the error reference id from the response structure.

Error reference id (or event id) should be logged to allow administrators match client-side events with cluster logs.

Returns
the pointer to string or NULL if ref wasn't specified.

◆ lcb_is_redacting_logs()

int lcb_is_redacting_logs ( lcb_t  instance)


Stability
Volatile:
Returns whether the library redacting logs for this connection instance.
Returns
non-zero if the logs are being redacted for this instance.