Couchbase C Client  2.10.0
Asynchronous C Client for Couchbase
vBucket

Detailed Description

These routines contain functionality for parsing a cluster topology configuration and mapping keys to cluster nodes appropriately.

Functions

lcbvb_CONFIGlcbvb_create (void)
 
Allocate a new config This can be used to create new config object and load it with a JSON config, optionally retrieving the error code More...
 
lcbvb_CONFIGlcbvb_parse_json (const char *data)
 
More...
 
int lcbvb_load_json (lcbvb_CONFIG *vbc, const char *data)
 
More...
 
int lcbvb_load_json_ex (lcbvb_CONFIG *vbc, const char *data, const char *source, char **network)
 
char * lcbvb_save_json (lcbvb_CONFIG *vbc)
 Serialize the current config as a JSON string. More...
 
const char * lcbvb_get_error (const lcbvb_CONFIG *vbc)
 
Return a string indicating why parsing the configuration failed More...
 
void lcbvb_replace_host (lcbvb_CONFIG *cfg, const char *hostname)
 
Replace hostname placeholders with specific host string This function shall replace hostname placeholists with the actual host string specified in hoststr. More...
 
void lcbvb_destroy (lcbvb_CONFIG *conf)
 
More...
 
int lcbvb_vbmaster (lcbvb_CONFIG *cfg, int vbid)
 
More...
 
int lcbvb_vbreplica (lcbvb_CONFIG *cfg, int vbid, unsigned ix)
 
More...
 
int lcbvb_nmv_remap_ex (lcbvb_CONFIG *cfg, int vbid, int bad, int use_heuristics)
 
More...
 
int lcbvb_map_key (lcbvb_CONFIG *cfg, const void *key, lcb_SIZE n, int *vbid, int *srvix)
 
More...
 
int lcbvb_k2vb (lcbvb_CONFIG *cfg, const void *key, lcb_SIZE n)
 
More...
 
int lcbvb_has_vbucket (lcbvb_CONFIG *vbc, int vbid, int ix)
 
More...
 
unsigned lcbvb_get_nservers (const lcbvb_CONFIG *cfg)
 Get the number of servers in the bucket. Note that not all servers may actually be available. More...
 
unsigned lcbvb_get_nreplicas (const lcbvb_CONFIG *cfg)
 Get the number of replicas the bucket is configured with Note that not all replicas may necessarily be online or available. More...
 
lcbvb_DISTMODE lcbvb_get_distmode (const lcbvb_CONFIG *cfg)
 Get the distribution mode (AKA bucket type) of the bucket. More...
 
int lcbvb_get_revision (const lcbvb_CONFIG *cfg)
 
Get the revision for this configuration. More...
 
unsigned lcbvb_get_port (lcbvb_CONFIG *cfg, unsigned ix, lcbvb_SVCTYPE type, lcbvb_SVCMODE mode)
 
Gets the port associated with a given service of a given mode on a given server More...
 
const char * lcbvb_get_hostport (lcbvb_CONFIG *cfg, unsigned ix, lcbvb_SVCTYPE type, lcbvb_SVCMODE mode)
 
Return a string for the given service This is like lcbvb_get_port but returns a string in the form of host:port rather than the numeric port More...
 
const char * lcbvb_get_hostname (const lcbvb_CONFIG *cfg, unsigned ix)
 
Get the hostname of a given server index. This may be used if all nodes reside on different hostnames, and can be used to answer the question of "which node does this index belong to" without having to perform additional string processing on the port of the string. More...
 
const char * lcbvb_get_resturl (lcbvb_CONFIG *cfg, unsigned ix, lcbvb_SVCTYPE type, lcbvb_SVCMODE mode)
 Function to return the URL prefix for a REST service. More...
 
int lcbvb_get_randhost (const lcbvb_CONFIG *cfg, lcbvb_SVCTYPE type, lcbvb_SVCMODE mode)
 Convenience function to select a random node for a service. More...
 
int lcbvb_get_randhost_ex (const lcbvb_CONFIG *cfg, lcbvb_SVCTYPE type, lcbvb_SVCMODE mode, int *used)
 Get random node, excluding nodes already tried. More...
 
lcbvb_CONFIGDIFFlcbvb_compare (lcbvb_CONFIG *from, lcbvb_CONFIG *to)
 
Compare two configurations and return information on the changes More...
 
void lcbvb_free_diff (lcbvb_CONFIGDIFF *diff)
 Free the structure returned by lcbvb_compare()
 
lcbvb_CHANGETYPE lcbvb_get_changetype (lcbvb_CONFIGDIFF *diff)
 Get a quick summary of the changes in the passed object. More...
 
int lcbvb_genconfig_ex (lcbvb_CONFIG *vb, const char *name, const char *uuid, const lcbvb_SERVER *servers, unsigned nservers, unsigned nreplica, unsigned nvbuckets)
 
Generate a sample configuration. More...
 
int lcbvb_genconfig (lcbvb_CONFIG *vb, unsigned nservers, unsigned nreplica, unsigned nvbuckets)
 
Generate a sample configuration used for testing. More...
 
void lcbvb_genffmap (lcbvb_CONFIG *vb)
 
More...
 
void lcbvb_make_ketama (lcbvb_CONFIG *vb)
 
More...
 
const char * lcbvb_get_capibase (lcbvb_CONFIG *cfg, unsigned ix, lcbvb_SVCMODE mode)
 
More...
 

Macros

#define LCBVB_NSERVERS(cfg)
 
#define LCBVB_NDATASERVERS(cfg)
 
#define LCBVB_NREPLICAS(cfg)
 
#define LCBVB_DISTTYPE(cfg)
 
#define LCBVB_CAPS(cfg)
 
#define LCBVB_GET_SERVER(conf, ix)
 
#define lcbvb_vbserver(cfg, vbid, ix)
 
More...
 
#define lcbvb_nmv_remap(cfg, vbid, bad)
 uncommitted Equivalent to More...
 

Typedefs

typedef struct lcbvb_CONFIGDIFF VBUCKET_CONFIG_DIFF
 
typedef enum lcbvb_CHANGETYPE VBUCKET_CHANGE_STATUS
 

Enumerations

enum  lcbvb_SVCTYPE
 This enum functions as a 'key' to indicate a specific service offered by a node. More...
 
enum  lcbvb_SVCMODE
 This enum functions to indicate the 'mode' of the service. More...
 
enum  lcbvb_DISTMODE
 Type of algorithm used to distribute keys. More...
 
enum  lcbvb_BUCKET_CAPABILITIES
 
enum  lcbvb_CHANGETYPE
 Convenience enum to determine the mode of change. More...
 

Function Documentation

◆ lcbvb_create()

lcbvb_CONFIG* lcbvb_create ( void  )


Allocate a new config This can be used to create new config object and load it with a JSON config, optionally retrieving the error code

Stability
Uncommitted:
if (0 != lcbvb_load_json(cfg, json)) {
printf("Got error!", lcbvb_get_error(cfg));
}

◆ lcbvb_parse_json()

lcbvb_CONFIG* lcbvb_parse_json ( const char *  data)


Stability
Uncommitted:
Parse the configuration string in data and return a new config object
Parameters
data
Returns
A new config object, or NULL on error.

◆ lcbvb_load_json()

int lcbvb_load_json ( lcbvb_CONFIG vbc,
const char *  data 
)


Stability
Committed:
Load a JSON-based configuration string into a configuration object
Parameters
vbcObject to populate
dataNUL-terminated string to parse
sourcehostname of the node, which emitted configuration. Pointer to NULL will disable heuristic when network argument is pointer to NULL string.
networkpointer to string, which specified key in alternative addresses dict. Use pointer NULL string to trigger heuristic, in this case, the function will try to match configuration source address to the list of addresses to determine best network.
Returns
0 on success, nonzero on failure
Note
it is recommended to use this function rather than lcbvb_parse_json() as this will contain the error string in the configuration in case of parse failures.

◆ lcbvb_save_json()

char* lcbvb_save_json ( lcbvb_CONFIG vbc)

Serialize the current config as a JSON string.

Stability
Volatile:
Serialize the current configuration as a JSON string. The string returned is NUL-terminated and should be freed using the free() function.

◆ lcbvb_get_error()

const char* lcbvb_get_error ( const lcbvb_CONFIG vbc)


Return a string indicating why parsing the configuration failed

Stability
Committed:
Returns
An error string. Do not free this string

◆ lcbvb_replace_host()

void lcbvb_replace_host ( lcbvb_CONFIG cfg,
const char *  hostname 
)


Replace hostname placeholders with specific host string This function shall replace hostname placeholists with the actual host string specified in hoststr.

Stability
Volatile:
Parameters
cfgthe configuration
hostnamethe actual hostname to use.

Use this immediately after a successful parsing of the configuration file.

◆ lcbvb_destroy()

void lcbvb_destroy ( lcbvb_CONFIG conf)


Stability
Committed:
Destroy the configuration object
Parameters
conf

◆ lcbvb_vbmaster()

int lcbvb_vbmaster ( lcbvb_CONFIG cfg,
int  vbid 
)


Stability
Committed:

Gets the master node index for the given vbucket

Parameters
cfgThe configuration
vbidThe vbucket to query
Returns
The master index. -1 if offline
Warning
This function does no bounds checking for vbid. Ensure it is within range of 0 < vbid < cfg->nvbs

◆ lcbvb_vbreplica()

int lcbvb_vbreplica ( lcbvb_CONFIG cfg,
int  vbid,
unsigned  ix 
)


Stability
Committed:

Return the 0-based replica index for the given vbucket.

Parameters
cfgThe configuration object
vbidThe vbucket to query
ixthe replica index to retrieve. This is a number ranging from 0 to vbc->nrepl exclusive.
Returns
The replica index, or -1 if offline
Warning
This function does no bounds checking for vbix or ix. Ensure that 0 < vbid < cfg->nvbs and -1 < ix < cfg->nrepl

◆ lcbvb_nmv_remap_ex()

int lcbvb_nmv_remap_ex ( lcbvb_CONFIG cfg,
int  vbid,
int  bad,
int  use_heuristics 
)


Stability
Uncommitted:

Using various guesswork and heuristics, attempt to locate an alternate node for the master of a given vbucket. This should be used if the master index is -1 or if the master index is deemed incorrect by some other means.

Parameters
cfgthe configuration object
vbidthe vbucket index to loop up
badthe index known to be bad. Passing this parameter allows the handler to safely call this function and be sure that a previous call's applied heuristics will not affect the modified map.
use_heuristicswhether additional heuristics should be used. If heuristics is off, only the fast-forward map is employed.

◆ lcbvb_map_key()

int lcbvb_map_key ( lcbvb_CONFIG cfg,
const void *  key,
lcb_SIZE  n,
int *  vbid,
int *  srvix 
)


Stability
Committed:

Map a given string to a vbucket and server

Parameters
cfgThe configuration object
keyKey to map
nLength of key
[out]vbidWill contain the vBucket
[out]srvixWill contain the server index
Returns
0 for now

◆ lcbvb_k2vb()

int lcbvb_k2vb ( lcbvb_CONFIG cfg,
const void *  key,
lcb_SIZE  n 
)


Stability
Committed:

Maps a key to a vBucket ID

Parameters
cfgThe configuration
keyThe key to retrieve
nThe size of the key
Returns
the vBucket for the key

◆ lcbvb_has_vbucket()

int lcbvb_has_vbucket ( lcbvb_CONFIG vbc,
int  vbid,
int  ix 
)


Stability
Uncommitted:
Determines if a given server index is either a master or a replica for a vbucket
Parameters
vbcthe configuration
vbidthe vbucket number
ixthe server index to check against
Returns
nonzero if the server ix is either a master or a replica for the vbucket vbid. Returns 0 otherwise.

◆ lcbvb_get_nservers()

unsigned lcbvb_get_nservers ( const lcbvb_CONFIG cfg)

Get the number of servers in the bucket. Note that not all servers may actually be available.

Stability
Committed:
Parameters
cfgThe configuration
Returns
The number of servers

◆ lcbvb_get_nreplicas()

unsigned lcbvb_get_nreplicas ( const lcbvb_CONFIG cfg)

Get the number of replicas the bucket is configured with Note that not all replicas may necessarily be online or available.

Stability
Committed:
Parameters
cfgthe configuration
Returns
the number of configured replicas

◆ lcbvb_get_distmode()

lcbvb_DISTMODE lcbvb_get_distmode ( const lcbvb_CONFIG cfg)

Get the distribution mode (AKA bucket type) of the bucket.

Stability
Committed:
Parameters
cfgthe configuration
Returns
the distribution mode

◆ lcbvb_get_revision()

int lcbvb_get_revision ( const lcbvb_CONFIG cfg)


Get the revision for this configuration.

Stability
Committed:

The revision is an integer which is increased each time the cluster generates a new configuration. This feature is available only on configurations generated by nodes of Couchbase Server v2.5 or later.

Parameters
cfgthe configuration
Returns
The revision ID, or -1 if the config does not have a revision

◆ lcbvb_get_port()

unsigned lcbvb_get_port ( lcbvb_CONFIG cfg,
unsigned  ix,
lcbvb_SVCTYPE  type,
lcbvb_SVCMODE  mode 
)


Gets the port associated with a given service of a given mode on a given server

Stability
Committed:
Parameters
cfgthe config object
ixthe index of the server to query
typethe type of service being provided
modethe mode of transport being used (e.g. plain, ssl)
Returns
a number greater than zero if the port exists, 0 otherwise

◆ lcbvb_get_hostport()

const char* lcbvb_get_hostport ( lcbvb_CONFIG cfg,
unsigned  ix,
lcbvb_SVCTYPE  type,
lcbvb_SVCMODE  mode 
)


Return a string for the given service This is like lcbvb_get_port but returns a string in the form of host:port rather than the numeric port

Stability
Committed:
Parameters
cfg
ix
type
mode
Returns
A string if the service is found, NULL otherwise. The storage duration of the string is valid until the configuration object is destroyed.

◆ lcbvb_get_hostname()

const char* lcbvb_get_hostname ( const lcbvb_CONFIG cfg,
unsigned  ix 
)


Get the hostname of a given server index. This may be used if all nodes reside on different hostnames, and can be used to answer the question of "which node does this index belong to" without having to perform additional string processing on the port of the string.

Stability
Committed:
Parameters
cfgthe configuration
ixthe index of the server to look up
Returns
a hostname without a port, or NULL if the index is out of bounds

◆ lcbvb_get_resturl()

const char* lcbvb_get_resturl ( lcbvb_CONFIG cfg,
unsigned  ix,
lcbvb_SVCTYPE  type,
lcbvb_SVCMODE  mode 
)

Function to return the URL prefix for a REST service.

Returns a string suitable for being passed as a URL. This is only valid for LCBVB_SVCTYPE_VIEWS and LCBVB_SVCTYPE_N1QL.

This function is different from lcbvb_get_hostport() – it is mainly a convenience, but does cache the string. Also, theoretically the cluster is free to choose a different URL prefix for a given service. Using this function will guarantee the URL prefix is correct.

◆ lcbvb_get_randhost()

int lcbvb_get_randhost ( const lcbvb_CONFIG cfg,
lcbvb_SVCTYPE  type,
lcbvb_SVCMODE  mode 
)

Convenience function to select a random node for a service.

Returns
0 or greater if a node was found; a negative number if no node contains a service with the given criteria.

◆ lcbvb_get_randhost_ex()

int lcbvb_get_randhost_ex ( const lcbvb_CONFIG cfg,
lcbvb_SVCTYPE  type,
lcbvb_SVCMODE  mode,
int *  used 
)

Get random node, excluding nodes already tried.

Parameters
cfgthe config
typetype of service
modetransport mode
usedan array of integers representing server indexes (should be of size LCBVB_NSERVERS). Servers whose indexes in the used array are nonzero will be skipped.
Returns
a server index, or -1 if no server remains (either because no server has the service, or because all available servers are in the exclude list)

◆ lcbvb_compare()

lcbvb_CONFIGDIFF* lcbvb_compare ( lcbvb_CONFIG from,
lcbvb_CONFIG to 
)


Compare two configurations and return information on the changes

Stability
Volatile:
Parameters
fromthe original configuration to use as the base
tothe new configuration
Returns
an object which may be inspected, or NULL on allocation failure. The returned object should be freed with lcbvb_free_diff()
See also
lcbvb_get_changetype()

◆ lcbvb_get_changetype()

lcbvb_CHANGETYPE lcbvb_get_changetype ( lcbvb_CONFIGDIFF diff)

Get a quick summary of the changes in the passed object.

Parameters
diffthe diff returned from lcbvb_compare()

◆ lcbvb_genconfig_ex()

int lcbvb_genconfig_ex ( lcbvb_CONFIG vb,
const char *  name,
const char *  uuid,
const lcbvb_SERVER servers,
unsigned  nservers,
unsigned  nreplica,
unsigned  nvbuckets 
)


Generate a sample configuration.

Stability
Volatile:
Parameters
vba new configuration object returned via lcbvb_create()
namethe name of the bucket
uuidUUID for the bucket
serversan array of server objects which will serve as the basis for the server list within the configuration. The memory pointed to by servers may be released after this function has completed
nserversnumber of servers in the array
nreplicahow many replicas for the bucket
nvbucketshow many vbuckets for the bucket

◆ lcbvb_genconfig()

int lcbvb_genconfig ( lcbvb_CONFIG vb,
unsigned  nservers,
unsigned  nreplica,
unsigned  nvbuckets 
)


Generate a sample configuration used for testing.

Stability
Volatile:
Parameters
vba new configuration object returned via lcbvb_create()
nservershow many nodes to place into the configuration
nreplicahow many replicas should be assigned to the bucket
nvbucketshow many vbuckets to create
Returns
0 on success, nonzero on error
Note
The base port for the lcbvb_SERVICES::data starts at 1000; the base port for lcbvb_SERVICES::views starts at 2000 and the base port for lcbvb_SERVICES::mgmt starts at 3000. The port number is incremented for each additional node.

◆ lcbvb_genffmap()

void lcbvb_genffmap ( lcbvb_CONFIG vb)


Stability
Volatile:
Generate a fast-forward vBucket map for the configuration. This simply provides alternate indices.

◆ lcbvb_make_ketama()

void lcbvb_make_ketama ( lcbvb_CONFIG vb)


Stability
Volatile:
Convert the configuration to a ketama one.
Parameters
vbThe configuration object.

◆ lcbvb_get_capibase()

const char* lcbvb_get_capibase ( lcbvb_CONFIG cfg,
unsigned  ix,
lcbvb_SVCMODE  mode 
)


Stability
Committed:

Get the views URL base.

Parameters
cfgThe configuration
ixThe index of the server to fetch
modeThe mode, either plain or ssl
Returns
A string reprenting the URL, or NULL if not available.

Data Structure Documentation

◆ lcbvb_SERVICES

struct lcbvb_SERVICES


Services which may be provided by a node

Stability
Volatile:
. ABI/API compatibility not guaranteed between versions
Data Fields
lcb_U16 data Data port for key-value operations (memcached protocol)
lcb_U16 mgmt Port for adminsitrative operations (HTTP)
lcb_U16 views Port for view queries (HTTP)
lcb_U16 ixquery Indexing query port.
lcb_U16 ixadmin Indexing admin port (HTTP)
lcb_U16 n1ql Query port.
lcb_U16 fts CBFT.
lcb_U16 cbas CBAS (Analytics)
char * views_base_ Views base URL.
char * query_base_ N1QL base URL.
char * fts_base_
char * cbas_base_
char * hoststrs[LCBVB_SVCTYPE__MAX]

◆ lcbvb_SERVER

struct lcbvb_SERVER


Node in the cluster This structure represents a node in the cluster. The node has a hostname (hostname), and various services.

Stability
Volatile:
. ABI/API compatibility not guaranteed between versions.
Data Fields
lcbvb_SERVICES svc Plain services.
lcbvb_SERVICES svc_ssl SSL Services.
char * authority host:dataport for comparison
char * hostname Hostname for the node.
char * viewpath Path prefix for view queries.
char * querypath Path prefix for n1ql queries.
char * ftspath Path prefix for fulltext queries.
char * cbaspath Path prefix for analytics queries.
unsigned nvbs Total number of vbuckets the server has assigned.
char * alt_hostname selected alternative hostname for the node
lcbvb_SERVICES alt_svc selected alternative plain services
lcbvb_SERVICES alt_svc_ssl selected alternative SSL Services

◆ lcbvb_VBUCKET

struct lcbvb_VBUCKET
Stability
Volatile:
. ABI/API compatibility not guaranteed between versions
Data Fields
int servers[4]

◆ lcbvb_CONTINUUM

struct lcbvb_CONTINUUM
Stability
Volatile:
Data Fields
lcb_U32 index
lcb_U32 point

◆ lcbvb_CONFIG

struct lcbvb_CONFIG

Structure containing the configuration.

Stability
Volatile:
. ABI/API compatibility not guaranteed between versions.
Data Fields
lcbvb_DISTMODE dtype Type of bucket/distribution.
unsigned nvb Number of vbuckets.
unsigned ndatasrv Number of data (memcached) servers.
unsigned nsrv
unsigned nrepl Number of servers.

Number of replicas

unsigned ncontinuum
unsigned is3x
int revid
char * buuid
char * bname
const char * errstr
lcbvb_SERVER * servers
lcbvb_VBUCKET * vbuckets
lcbvb_VBUCKET * ffvbuckets
lcbvb_CONTINUUM * continuum
int * randbuf
long caps Server capabilities.

◆ lcbvb_CONFIGDIFF

struct lcbvb_CONFIGDIFF

Structure representing changes between two configurations.

Data Fields
char ** servers_added List of strings of servers added (via host:data_port)
char ** servers_removed List of strings of servers removed (via host:data_port)
int n_vb_changes How many vBuckets have had an ownership change.
int sequence_changed Whether the ordering of the nodes has changed as well.

Macro Definition Documentation

◆ lcbvb_vbserver

#define lcbvb_vbserver (   cfg,
  vbid,
  ix 
)


Stability
Volatile:
This allows to get the given index for a vbucket server. If the index is 0 then this returns the master index, if the index is greater then it returns the replica index

◆ lcbvb_nmv_remap

#define lcbvb_nmv_remap (   cfg,
  vbid,
  bad 
)

uncommitted Equivalent to

lcbvb_nmv_remap_ex(cfg, vbid, bad, 0);

Enumeration Type Documentation

◆ lcbvb_SVCTYPE

This enum functions as a 'key' to indicate a specific service offered by a node.

Enumerator
LCBVB_SVCTYPE_DATA 

memcached/Data port

LCBVB_SVCTYPE_VIEWS 

Views/CAPI port.

LCBVB_SVCTYPE_MGMT 

Administrative/'REST' UI.

LCBVB_SVCTYPE_IXQUERY 

Index query.

LCBVB_SVCTYPE_IXADMIN 

Index administration.

LCBVB_SVCTYPE_N1QL 

N1QL Query.

LCBVB_SVCTYPE_FTS 

Fulltext.

LCBVB_SVCTYPE_ANALYTICS 

Analytics Query.

◆ lcbvb_SVCMODE

This enum functions to indicate the 'mode' of the service.

Currently this is to distinguish between SSL and plain transports

Enumerator
LCBVB_SVCMODE_PLAIN 

Plain transport.

LCBVB_SVCMODE_SSL 

SSL Transport.

◆ lcbvb_DISTMODE

Type of algorithm used to distribute keys.

This also indicates the type of bucket

Enumerator
LCBVB_DIST_VBUCKET 

vBucket hashing ("couchbase") bucket

LCBVB_DIST_KETAMA 

Ketama hashing ("memcached") bucket.

◆ lcbvb_CHANGETYPE

Convenience enum to determine the mode of change.

Enumerator
LCBVB_NO_CHANGES 

No changes between configs.

LCBVB_SERVERS_MODIFIED 

Servers have been added or removed.

LCBVB_MAP_MODIFIED 

vBuckets have been transferred