Detailed Description

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

Functions
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. More...

lcbvb_CONFIG *	lcbvb_parse_json (const char *data)

int	lcbvb_load_json (lcbvb_CONFIG vbc, const char data)

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)

int	lcbvb_vbmaster (lcbvb_CONFIG *cfg, int vbid)

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

int	lcbvb_nmv_remap (lcbvb_CONFIG *cfg, int vbid, int bad)

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

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

int	lcbvb_has_vbucket (lcbvb_CONFIG *vbc, int vbid, int ix)
	uncommitted Determines if a given server index is either a master or a replica for a vbucket 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...

lcbvb_CONFIGDIFF *	lcbvb_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_make_ketama (lcbvb_CONFIG *vb)

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

Macros
#define	LCBVB_NSERVERS(cfg)

#define	LCBVB_NREPLICAS(cfg)

#define	LCBVB_DISTTYPE(cfg)

#define	LCBVB_GET_SERVER(conf, ix)

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_CHANGETYPE
	Convenience enum to determine the mode of change. More...

Function Documentation

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:

lcbvb_CONFIG *cfg = lcbvb_create();
if (0 != lcbvb_load_json(cfg, json)) {
  printf("Got error!", lcbvb_get_error(cfg));
  lcbvb_destroy(cfg);
}

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.

int lcbvb_load_json	(	lcbvb_CONFIG *	vbc,
		const char *	data
	)

Stability

Committed:

Load a JSON-based configuration string into a configuration object

Parameters

vbc	Object to populate
data	NUL-terminated string to parse

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.

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.

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

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

cfg	the configuration
hostname	the actual hostname to use.

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

void lcbvb_destroy ( lcbvb_CONFIG * conf )

Stability

Committed:

Destroy the configuration object

Parameters

conf

int lcbvb_vbmaster	(	lcbvb_CONFIG *	cfg,
		int	vbid
	)

Stability

Committed:

Gets the master node index for the given vbucket

Parameters

cfg	The configuration
vbid	The 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

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

Stability

Committed:

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

Parameters

cfg	The configuration object
vbid	The vbucket to query
ix	the 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

int lcbvb_nmv_remap	(	lcbvb_CONFIG *	cfg,
		int	vbid,
		int	bad
	)

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

cfg	the configuration object
vbix	the vbucket index to loop up
bad	the 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.

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

	cfg	The configuration object
	key	Key to map
	n	Length of key
[out]	vbid	Will contain the vBucket
[out]	srvix	Will contain the server index

Returns: 0 for now

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

Stability

Committed:

Maps a key to a vBucket ID

Parameters

cfg	The configuration
key	The key to retrieve
n	The size of the key

Returns: the vBucket for the key

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

uncommitted Determines if a given server index is either a master or a replica for a vbucket

Parameters

vbc	the configuration
vbid	the vbucket number
ix	the 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.

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

cfg	The configuration

Returns: The number of servers

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

cfg	the configuration

Returns: the number of configured replicas

lcbvb_DISTMODE lcbvb_get_distmode ( const lcbvb_CONFIG * cfg )

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

Stability

Committed:

Parameters

cfg	the configuration

Returns: the distribution mode

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

cfg	the configuration

Returns: The revision ID, or -1 if the config does not have a revision

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

cfg	the config object
ix	the index of the server to query
type	the type of service being provided
mode	the mode of transport being used (e.g. plain, ssl)

Returns: a number greater than zero if the port exists, 0 otherwise

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_CONFIGDIFF* lcbvb_compare	(	lcbvb_CONFIG *	from,
		lcbvb_CONFIG *	to
	)

Compare two configurations and return information on the changes.

Stability

Volatile:

Parameters

from	the original configuration to use as the base
to	the 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_CHANGETYPE lcbvb_get_changetype ( lcbvb_CONFIGDIFF * diff )

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

Parameters

diff	the diff returned from lcbvb_compare()

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

vb	a new configuration object returned via lcbvb_create()
name	the name of the bucket
uuid	UUID for the bucket
servers	an 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
nservers	number of servers in the array
nreplica	how many replicas for the bucket
nvbuckets	how many vbuckets for the bucket

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

Generate a sample configuration used for testing.

Stability

Volatile:

Parameters

vb	a new configuration object returned via lcbvb_create()
nservers	how many nodes to place into the configuration
nreplica	how many replicas should be assigned to the bucket
nvbuckets	how 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.

void lcbvb_make_ketama ( lcbvb_CONFIG * vb )

Stability

Volatile:

Convert the configuration to a ketama one.

Parameters

vb	The configuration object.

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

Stability

Committed:

Get the views URL base.

Parameters

cfg	The configuration
ix	The index of the server to fetch
mode	The mode, either plain or ssl

Returns: A string reprenting the URL, or NULL if not available.

Data Structure Documentation

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)
char *	views_base_	Views base URL.
char *	hoststrs[LCBVB_SVCTYPE__MAX]

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.
unsigned	nvbs	Total number of vbuckets the server has assigned.

struct lcbvb_VBUCKET

Stability

Volatile:: . ABI/API compatibility not guaranteed between versions

Data Fields
int	servers[4]

struct lcbvb_CONTINUUM

Stability

Volatile:

Data Fields
lcb_U32	index
lcb_U32	point

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	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

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.

Enumeration Type Documentation

enum 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.

enum 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.

enum 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.

enum 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

Detailed Description

Functions

Macros

Typedefs

Enumerations

Function Documentation

Data Structure Documentation

Enumeration Type Documentation