These routines contain functionality for parsing a cluster topology configuration and mapping keys to cluster nodes appropriately.
◆ lcbvb_create()
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
}
int lcbvb_load_json(lcbvb_CONFIG *vbc, const char *data)
const char * lcbvb_get_error(const lcbvb_CONFIG *vbc)
Return a string indicating why parsing the configuration failed.
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,...
void lcbvb_destroy(lcbvb_CONFIG *conf)
Structure containing the configuration.
Definition vbucket.h:155
◆ lcbvb_parse_json()
- Stability
- Uncommitted
- Parse the configuration string in
data
and return a new config object
- Parameters
-
- 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
-
vbc | Object to populate |
data | NUL-terminated string to parse |
source | hostname of the node, which emitted configuration. Pointer to NULL will disable heuristic when network argument is pointer to NULL string. |
network | pointer 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_load_json_ex()
int lcbvb_load_json_ex |
( |
lcbvb_CONFIG * | vbc, |
|
|
const char * | data, |
|
|
const char * | source, |
|
|
char ** | network ) |
◆ lcbvb_save_json()
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()
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
-
cfg | the configuration |
hostname | the actual hostname to use. |
Use this immediately after a successful parsing of the configuration file.
◆ lcbvb_destroy()
- Stability
- Committed
- Destroy the configuration object
- Parameters
-
◆ lcbvb_vbmaster()
- 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
◆ 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
-
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
◆ 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
-
cfg | the configuration object |
vbid | 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. |
use_heuristics | whether 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
-
| 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
◆ lcbvb_k2vb()
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
◆ 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
-
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.
◆ lcbvb_get_nservers()
Get the number of servers in the bucket. Note that not all servers may actually be available.
- Stability
- Committed
- Parameters
-
- Returns
- The number of servers
◆ lcbvb_get_nreplicas()
Get the number of replicas the bucket is configured with Note that not all replicas may necessarily be online or available.
- Stability
- Committed
- Parameters
-
- Returns
- the number of configured replicas
◆ lcbvb_get_nvbuckets()
Get the number of vbuckets the bucket is configured with.
- Stability
- Committed
- Returns
- the number of vbuckets, or zero if not applicable
◆ lcbvb_get_distmode()
Get the distribution mode (AKA bucket type) of the bucket.
- Stability
- Committed
- Parameters
-
- Returns
- the distribution mode
◆ lcbvb_get_revision()
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
-
- Returns
- The revision ID, or
-1
if the config does not have a revision
◆ lcbvb_get_port()
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
◆ lcbvb_get_hostport()
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
-
- 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
-
cfg | the configuration |
ix | the 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()
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_QUERY.
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()
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()
Get random node, excluding nodes already tried.
- Parameters
-
cfg | the config |
type | type of service |
mode | transport mode |
used | an 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()
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_get_changetype()
Get a quick summary of the changes in the passed object.
- Parameters
-
◆ 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
-
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 |
◆ lcbvb_genconfig()
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.
◆ lcbvb_genffmap()
- Stability
- Volatile
- Generate a fast-forward vBucket map for the configuration. This simply provides alternate indices.
◆ lcbvb_make_ketama()
- Stability
- Volatile
- Convert the configuration to a ketama one.
- Parameters
-
vb | The configuration object. |
◆ lcbvb_get_capibase()
- 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.
◆ lcbvb_SERVICES
◆ lcbvb_SERVER
◆ lcbvb_VBUCKET
◆ lcbvb_CONTINUUM
◆ lcbvb_CONFIG
◆ lcbvb_CONFIGDIFF
◆ 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
int lcbvb_nmv_remap_ex(lcbvb_CONFIG *cfg, int vbid, int bad, int use_heuristics)
◆ 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_QUERY | N1QL Query.
|
LCBVB_SVCTYPE_SEARCH | Fulltext.
|
LCBVB_SVCTYPE_ANALYTICS | Analytics Query.
|
LCBVB_SVCTYPE_EVENTING | Eventing Management.
|
◆ 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_DIST_UNKNOWN | Unknown distribution (cluster config)
|
◆ 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
|
LCBVB_REPLICAS_MODIFIED | number of replicas has been modified
|