libcouchbase 0.0.1

data/ext/libcouchbase/include/libcouchbase/sysdefs.h

@@ -0,0 +1,98 @@
+/* -*- Mode: C; tab-width: 4; c-basic-offset: 4; indent-tabs-mode: nil -*- */
+/*
+ *     Copyright 2010-2012 Couchbase, Inc.
+ *
+ *   Licensed under the Apache License, Version 2.0 (the "License");
+ *   you may not use this file except in compliance with the License.
+ *   You may obtain a copy of the License at
+ *
+ *       http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *   Unless required by applicable law or agreed to in writing, software
+ *   distributed under the License is distributed on an "AS IS" BASIS,
+ *   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *   See the License for the specific language governing permissions and
+ *   limitations under the License.
+ */
+
+/**
+ * Basic platform includes.
+ */
+#ifndef LCB_SYSDEFS_H
+#define LCB_SYSDEFS_H
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#ifdef _WIN32
+    #include <stddef.h>
+    #include <winsock2.h>
+    #include <basetsd.h>
+
+    typedef __int64 lcb_int64_t;
+    typedef __int32 lcb_int32_t;
+    typedef SIZE_T lcb_size_t;
+    typedef SSIZE_T lcb_ssize_t;
+    typedef unsigned __int8 lcb_uint8_t;
+    typedef unsigned __int16 lcb_vbucket_t;
+    typedef unsigned __int16 lcb_uint16_t;
+    typedef unsigned __int32 lcb_uint32_t;
+    typedef unsigned __int64 lcb_cas_t;
+    typedef unsigned __int64 lcb_uint64_t;
+
+    /** FIXME: This should be a native type, but it's already defined here.. */
+    typedef unsigned __int32 lcb_time_t;
+#else
+    #include <sys/types.h>
+    #include <stdint.h>
+    #include <time.h>
+
+    #if defined(__STDC_VERSION__) && __STDC_VERSION__ >= 199901L
+    #include <stddef.h>
+    #endif
+
+    typedef int64_t lcb_int64_t;
+    typedef int32_t lcb_int32_t;
+    typedef size_t lcb_size_t;
+    typedef ssize_t lcb_ssize_t;
+    typedef uint16_t lcb_vbucket_t;
+    typedef uint8_t lcb_uint8_t;
+    typedef uint16_t lcb_uint16_t;
+    typedef uint32_t lcb_uint32_t;
+    typedef uint64_t lcb_cas_t;
+    typedef uint64_t lcb_uint64_t;
+    typedef time_t lcb_time_t;
+#endif
+
+typedef lcb_int64_t lcb_S64; /**< @brief Signed 64 bit type */
+typedef lcb_uint64_t lcb_U64; /**< @brief Unsigned 64 bit type */
+typedef lcb_uint32_t lcb_U32; /**< @brief Unsigned 32 bit type */
+typedef lcb_int32_t lcb_S32; /**< @brief Signed 32 bit type */
+typedef lcb_uint16_t lcb_U16; /**< @brief Unsigned 16 bit type */
+typedef lcb_uint8_t lcb_U8; /**< @brief unsigned 8 bit type */
+typedef lcb_size_t lcb_SIZE; /**< @brief Unsigned size type */
+typedef lcb_ssize_t lcb_SSIZE; /**<@brief Signed size type */
+typedef lcb_time_t lcb_SECS; /**< @brief Unsigned 'seconds time' type */
+typedef lcb_cas_t lcb_CAS;
+
+#ifdef __GNUC__
+#define LCB_DEPRECATED(X) X __attribute__((deprecated))
+    #if __GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 7)
+    #define LCB_DEPRECATED2(X, reason) X __attribute__((deprecated(reason)))
+    #else
+    #define LCB_DEPRECATED2(X, reason) LCB_DEPRECATED(X)
+    #endif
+#elif defined(_MSC_VER)
+#define LCB_DEPRECATED(X) __declspec(deprecated) X
+#define LCB_DEPRECATED2(X, reason) __declspec(deprecated(reason)) X
+#else
+#define LCB_DEPRECATED(X) X
+#define LCB_DEPRECATED2(X, reason)
+#endif
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* LCB_SYSDEFS_H */

data/ext/libcouchbase/include/libcouchbase/vbucket.h

@@ -0,0 +1,643 @@
+/* -*- Mode: C; tab-width: 4; c-basic-offset: 4; indent-tabs-mode: nil -*- */
+/*
+ *     Copyright 2014 Couchbase, Inc.
+ *
+ *   Licensed under the Apache License, Version 2.0 (the "License");
+ *   you may not use this file except in compliance with the License.
+ *   You may obtain a copy of the License at
+ *
+ *       http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *   Unless required by applicable law or agreed to in writing, software
+ *   distributed under the License is distributed on an "AS IS" BASIS,
+ *   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *   See the License for the specific language governing permissions and
+ *   limitations under the License.
+ */
+
+#ifndef LCB_VBUCKET_H
+#define LCB_VBUCKET_H
+#include <libcouchbase/visibility.h>
+#include <libcouchbase/sysdefs.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * @file
+ * @brief vBucket Mapping API
+ */
+
+/**
+ * @ingroup lcb-public-api
+ * @defgroup lcb-vbucket-api vBucket
+ * @details
+ * These routines contain functionality for parsing a cluster topology configuration
+ * and mapping keys to cluster nodes appropriately.
+ */
+
+/**
+ * @addtogroup lcb-vbucket-api
+ * @{
+ */
+
+/**@brief This enum functions as a 'key' to indicate a specific service offered
+ * by a node */
+typedef enum {
+    LCBVB_SVCTYPE_DATA = 0, /**< 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__MAX
+} lcbvb_SVCTYPE;
+
+/**@brief This enum functions to indicate the 'mode' of the service. Currently
+ * this is to distinguish between SSL and plain transports */
+typedef enum {
+    LCBVB_SVCMODE_PLAIN = 0, /**< Plain transport */
+    LCBVB_SVCMODE_SSL, /**< SSL Transport */
+    LCBVB_SVCMODE__MAX
+} lcbvb_SVCMODE;
+
+/**
+ * @volatile. ABI/API compatibility not guaranteed between versions
+ * @brief Services which may be provided by a node
+ */
+typedef struct {
+    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 */
+    char *views_base_; /**< Views base URL */
+    char *query_base_; /**< N1QL base URL */
+    char *fts_base_;
+    char *hoststrs[LCBVB_SVCTYPE__MAX];
+} lcbvb_SERVICES;
+
+/**
+ * @volatile. ABI/API compatibility not guaranteed between versions.
+ *
+ * @brief Node in the cluster
+ * This structure represents a node in the cluster. The node has a hostname
+ * (@ref #hostname), and various services.
+ */
+typedef struct {
+    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 */
+    unsigned nvbs; /**< Total number of vbuckets the server has assigned */
+} lcbvb_SERVER;
+
+/**@volatile. ABI/API compatibility not guaranteed between versions */
+typedef struct {
+    int servers[4];
+} lcbvb_VBUCKET;
+
+/**@volatile*/
+typedef struct {
+    lcb_U32 index;
+    lcb_U32 point;
+} lcbvb_CONTINUUM;
+
+/** @brief Type of algorithm used to distribute keys.
+ * This also indicates the type of bucket */
+typedef enum {
+    LCBVB_DIST_VBUCKET = 0, /**< vBucket hashing ("couchbase") bucket */
+    LCBVB_DIST_KETAMA = 1 /**< Ketama hashing ("memcached") bucket */
+} lcbvb_DISTMODE;
+
+/**@volatile. ABI/API compatibility not guaranteed between versions.
+ * @brief Structure containing the configuration.*/
+typedef struct lcbvb_CONFIG_st {
+    lcbvb_DISTMODE dtype; /**< Type of bucket/distribution */
+    unsigned nvb; /**< Number of vbuckets */
+    unsigned ndatasrv; /**< Number of data (memcached) servers */
+    unsigned nsrv; /** Number of servers */
+    unsigned nrepl; /**< Number of replicas */
+    unsigned ncontinuum; /* number of continuum points */
+    unsigned is3x; /* whether server 3.0 config semantics are in place */
+    int revid; /* revision ID from the config (-1 if not present) */
+    char *buuid; /* bucket UUID */
+    char *bname; /* bucket name */
+    const char *errstr; /* last error */
+    lcbvb_SERVER *servers; /* nodes */
+    lcbvb_VBUCKET *vbuckets; /* vbucket map */
+    lcbvb_VBUCKET *ffvbuckets; /* fast-forward map */
+    lcbvb_CONTINUUM *continuum; /* ketama continuums */
+    int *randbuf; /* Used for random server selection */
+} lcbvb_CONFIG;
+
+
+#define LCBVB_NSERVERS(cfg) (cfg)->nsrv
+#define LCBVB_NDATASERVERS(cfg) (cfg)->ndatasrv
+#define LCBVB_NREPLICAS(cfg) (cfg)->nrepl
+#define LCBVB_DISTTYPE(cfg) (cfg)->dtype
+#define LCBVB_GET_SERVER(conf, ix) ((conf)->servers + ix)
+
+/**
+ * @uncommitted
+ * @brief 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
+ * @code{.c}
+ * lcbvb_CONFIG *cfg = lcbvb_create();
+ * if (0 != lcbvb_load_json(cfg, json)) {
+ *   printf("Got error!", lcbvb_get_error(cfg));
+ *   lcbvb_destroy(cfg);
+ * }
+ * @endcode
+ */
+LIBCOUCHBASE_API
+lcbvb_CONFIG *
+lcbvb_create(void);
+
+/**
+ * @uncommitted
+ * Parse the configuration string in `data` and return a new config object
+ * @param data
+ * @return A new config object, or NULL on error.
+ */
+LIBCOUCHBASE_API
+lcbvb_CONFIG *
+lcbvb_parse_json(const char *data);
+
+/**
+ * @committed
+ * Load a JSON-based configuration string into a configuration object
+ * @param vbc Object to populate
+ * @param data NUL-terminated string to parse
+ * @return 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.
+ */
+LIBCOUCHBASE_API
+int
+lcbvb_load_json(lcbvb_CONFIG *vbc, const char *data);
+
+/**@brief Serialize the current config as a JSON string.
+ * @volatile
+ * Serialize the current configuration as a JSON string. The string returned is
+ * NUL-terminated and should be freed using the free() function.
+ */
+LIBCOUCHBASE_API
+char *
+lcbvb_save_json(lcbvb_CONFIG *vbc);
+
+/**
+ * @committed
+ * @brief Return a string indicating why parsing the configuration failed
+ * @return An error string. Do not free this string
+ */
+LIBCOUCHBASE_API
+const char *
+lcbvb_get_error(const lcbvb_CONFIG *vbc);
+
+/**
+ * @volatile
+ * @brief Replace hostname placeholders with specific host string
+ * This function shall replace hostname placeholists with the actual host string
+ * specified in `hoststr`.
+ * @param cfg the configuration
+ * @param hostname the actual hostname to use.
+ *
+ * Use this immediately after a successful parsing of the configuration file.
+ */
+LIBCOUCHBASE_API
+void
+lcbvb_replace_host(lcbvb_CONFIG *cfg, const char *hostname);
+
+/**
+ * @committed
+ * Destroy the configuration object
+ * @param conf
+ */
+LIBCOUCHBASE_API
+void
+lcbvb_destroy(lcbvb_CONFIG *conf);
+
+/**
+ * @committed
+ *
+ * Gets the master node index for the given vbucket
+ * @param cfg The configuration
+ * @param vbid The vbucket to query
+ * @return 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`
+ */
+LIBCOUCHBASE_API
+int
+lcbvb_vbmaster(lcbvb_CONFIG *cfg, int vbid);
+
+/**
+ * @committed
+ *
+ * Return the 0-based replica index for the given vbucket.
+ * @param cfg The configuration object
+ * @param vbid The vbucket to query
+ * @param ix the replica index to retrieve. This is a number ranging from
+ *        0 to vbc->nrepl exclusive.
+ * @return 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`
+ */
+LIBCOUCHBASE_API
+int
+lcbvb_vbreplica(lcbvb_CONFIG *cfg, int vbid, unsigned ix);
+
+/**
+ * @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
+ */
+#define lcbvb_vbserver(cfg, vbid, ix) ( (ix == 0) ? \
+        lcbvb_vbmaster(cfg, vbid) : lcbvb_vbreplica(cfg, vbid, ix-1) )
+
+
+/**
+ * uncommitted
+ * Equivalent to
+ * @code{.c}
+ * lcbvb_nmv_remap_ex(cfg, vbid, bad, 0);
+ * @endcode
+ */
+#define lcbvb_nmv_remap(cfg, vbid, bad) lcbvb_nmv_remap_ex(cfg, vbid, bad, 0)
+
+/**
+ * @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.
+ *
+ * @param cfg the configuration object
+ * @param vbid the vbucket index to loop up
+ * @param 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.
+ * @param use_heuristics whether additional heuristics should be used. If
+ *  heuristics is off, only the fast-forward map is employed.
+ */
+int
+lcbvb_nmv_remap_ex(lcbvb_CONFIG *cfg, int vbid, int bad, int use_heuristics);
+
+/**
+ * @committed
+ *
+ * Map a given string to a vbucket and server
+ * @param cfg The configuration object
+ * @param key Key to map
+ * @param n Length of key
+ * @param[out] vbid Will contain the vBucket
+ * @param[out] srvix Will contain the server index
+ * @return 0 for now
+ */
+LIBCOUCHBASE_API
+int
+lcbvb_map_key(lcbvb_CONFIG *cfg, const void *key, lcb_SIZE n,
+    int *vbid, int *srvix);
+
+/**
+ * @committed
+ *
+ * Maps a key to a vBucket ID
+ * @param cfg The configuration
+ * @param key The key to retrieve
+ * @param n The size of the key
+ * @return the vBucket for the key
+ */
+LIBCOUCHBASE_API
+int
+lcbvb_k2vb(lcbvb_CONFIG *cfg, const void *key, lcb_SIZE n);
+
+/**
+ * @uncomitted
+ * Determines if a given server index is either a master or a replica for a
+ * vbucket
+ * @param vbc the configuration
+ * @param vbid the vbucket number
+ * @param 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.
+ */
+LIBCOUCHBASE_API
+int
+lcbvb_has_vbucket(lcbvb_CONFIG *vbc, int vbid, int ix);
+
+/**@committed
+ * @brief Get the number of servers in the bucket. Note that not all servers
+ * may actually be available.
+ * @param cfg The configuration
+ * @return The number of servers
+ **/
+LIBCOUCHBASE_API
+unsigned
+lcbvb_get_nservers(const lcbvb_CONFIG *cfg);
+
+/**@committed
+ * @brief Get the number of replicas the bucket is configured with
+ * Note that not all replicas may necessarily be online or available.
+ * @param cfg the configuration
+ * @return the number of configured replicas
+ */
+LIBCOUCHBASE_API
+unsigned
+lcbvb_get_nreplicas(const lcbvb_CONFIG *cfg);
+
+/**@committed
+ * @brief Get the distribution mode (AKA bucket type) of the bucket
+ * @param cfg the configuration
+ * @return the distribution mode
+ */
+LIBCOUCHBASE_API
+lcbvb_DISTMODE
+lcbvb_get_distmode(const lcbvb_CONFIG *cfg);
+
+/**
+ * @committed
+ *
+ * @brief Get the revision for this configuration.
+ *
+ * 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.
+ *
+ * @param cfg the configuration
+ * @return The revision ID, or `-1` if the config does not have a revision
+ */
+LIBCOUCHBASE_API
+int
+lcbvb_get_revision(const lcbvb_CONFIG *cfg);
+
+/**
+ * @committed
+ * @brief Gets the port associated with a given service of a given mode on a given
+ * server
+ * @param cfg the config object
+ * @param ix the index of the server to query
+ * @param type the type of service being provided
+ * @param mode the mode of transport being used (e.g. plain, ssl)
+ * @return a number greater than zero if the port exists, 0 otherwise
+ */
+LIBCOUCHBASE_API
+unsigned
+lcbvb_get_port(lcbvb_CONFIG *cfg, unsigned ix,
+    lcbvb_SVCTYPE type, lcbvb_SVCMODE mode);
+
+
+/**
+ * @committed
+ *
+ * @brief 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
+ *
+ * @param cfg
+ * @param ix
+ * @param type
+ * @param mode
+ * @return A string if the service is found, NULL otherwise. The storage
+ * duration of the string is valid until the configuration object is
+ * destroyed.
+ */
+LIBCOUCHBASE_API
+const char *
+lcbvb_get_hostport(lcbvb_CONFIG *cfg, unsigned ix,
+    lcbvb_SVCTYPE type, lcbvb_SVCMODE mode);
+
+/**
+ * @committed
+ *
+ * @brief 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.
+ *
+ * @param cfg the configuration
+ * @param ix the index of the server to look up
+ * @return a hostname without a port, or NULL if the index is out of bounds
+ */
+LIBCOUCHBASE_API
+const char *
+lcbvb_get_hostname(const lcbvb_CONFIG *cfg, unsigned ix);
+
+/**
+ * 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.
+ */
+LIBCOUCHBASE_API
+const char *
+lcbvb_get_resturl(lcbvb_CONFIG *cfg, unsigned ix,
+    lcbvb_SVCTYPE type, lcbvb_SVCMODE mode);
+
+/**
+ * Convenience function to select a random node for a service.
+ * @return 0 or greater if a node was found; a negative number if no node
+ * contains a service with the given criteria.
+ */
+LIBCOUCHBASE_API
+int
+lcbvb_get_randhost(const lcbvb_CONFIG *cfg,
+    lcbvb_SVCTYPE type, lcbvb_SVCMODE mode);
+
+/**
+ * Get random node, excluding nodes already tried
+ * @param cfg the config
+ * @param type type of service
+ * @param mode transport mode
+ * @param 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*.
+ *
+ * @return 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)
+ */
+LIBCOUCHBASE_API
+int
+lcbvb_get_randhost_ex(const lcbvb_CONFIG *cfg,
+    lcbvb_SVCTYPE type, lcbvb_SVCMODE mode, int *used);
+
+/** @brief Structure representing changes between two configurations */
+typedef struct {
+    /** List of strings of servers added (via `host:data_port`) */
+    char **servers_added;
+    /** List of strings of servers removed (via `host:data_port`) */
+    char **servers_removed;
+    /** How many vBuckets have had an ownership change */
+    int n_vb_changes;
+    /** Whether the ordering of the nodes has changed as well */
+    int sequence_changed;
+} lcbvb_CONFIGDIFF, VBUCKET_CONFIG_DIFF;
+
+/** @brief Convenience enum to determine the mode of change */
+typedef enum {
+    LCBVB_NO_CHANGES = 0, /**< No changes between configs */
+    LCBVB_SERVERS_MODIFIED = 1 << 0, /**< Servers have been added or removed */
+    LCBVB_MAP_MODIFIED = 1 << 1 /**< vBuckets have been transferred */
+} lcbvb_CHANGETYPE, VBUCKET_CHANGE_STATUS;
+
+/**
+ * @volatile
+ *
+ * @brief Compare two configurations and return information on the changes
+ * @param from the original configuration to use as the base
+ * @param to the new configuration
+ * @return an object which may be inspected, or NULL on allocation failure. The
+ *         returned object should be freed with lcbvb_free_diff()
+ * @see lcbvb_get_changetype()
+ */
+LIBCOUCHBASE_API
+lcbvb_CONFIGDIFF *
+lcbvb_compare(lcbvb_CONFIG *from, lcbvb_CONFIG *to);
+
+/** @brief Free the structure returned by lcbvb_compare() */
+LIBCOUCHBASE_API
+void
+lcbvb_free_diff(lcbvb_CONFIGDIFF *diff);
+
+/**@brief Get a quick summary of the changes in the passed object
+ * @param diff the diff returned from lcbvb_compare()
+ */
+LIBCOUCHBASE_API
+lcbvb_CHANGETYPE
+lcbvb_get_changetype(lcbvb_CONFIGDIFF *diff);
+
+/**
+ * @volatile
+ *
+ * @brief Generate a sample configuration.
+ * @param vb a new configuration object returned via lcbvb_create()
+ * @param name the name of the bucket
+ * @param uuid UUID for the bucket
+ * @param 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
+ * @param nservers number of servers in the array
+ * @param nreplica how many replicas for the bucket
+ * @param nvbuckets how many vbuckets for the bucket
+ */
+LIBCOUCHBASE_API
+int
+lcbvb_genconfig_ex(lcbvb_CONFIG *vb,
+    const char *name, const char *uuid,
+    const lcbvb_SERVER *servers,
+    unsigned nservers, unsigned nreplica, unsigned nvbuckets);
+
+/**
+ * @volatile
+ *
+ * @brief Generate a sample configuration used for testing.
+ * @param vb a new configuration object returned via lcbvb_create()
+ * @param nservers how many nodes to place into the configuration
+ * @param nreplica how many replicas should be assigned to the bucket
+ * @param nvbuckets how many vbuckets to create
+ * @return 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.
+ */
+LIBCOUCHBASE_API
+int
+lcbvb_genconfig(lcbvb_CONFIG *vb,
+    unsigned nservers, unsigned nreplica, unsigned nvbuckets);
+
+/**
+ * @volatile
+ * Generate a fast-forward vBucket map for the configuration. This simply
+ * provides alternate indices.
+ */
+LIBCOUCHBASE_API
+void
+lcbvb_genffmap(lcbvb_CONFIG *vb);
+
+
+/**
+ * @volatile
+ * Convert the configuration to a ketama one.
+ * @param vb The configuration object.
+ */
+LIBCOUCHBASE_API
+void
+lcbvb_make_ketama(lcbvb_CONFIG *vb);
+
+/**
+ * @committed
+ *
+ * Get the views URL base.
+ * @param cfg The configuration
+ * @param ix The index of the server to fetch
+ * @param mode The mode, either plain or ssl
+ * @return A string reprenting the URL, or NULL if not available.
+ */
+LIBCOUCHBASE_API
+const char *
+lcbvb_get_capibase(lcbvb_CONFIG *cfg, unsigned ix, lcbvb_SVCMODE mode);
+/**@}*/
+
+/*the rest of these symbols are deprecated and should not be touched by
+ * doxygen */
+
+typedef enum {
+    LIBVBUCKET_SOURCE_FILE,
+    LIBVBUCKET_SOURCE_MEMORY
+} vbucket_source_t;
+
+typedef lcbvb_CONFIG *VBUCKET_CONFIG_HANDLE;
+typedef lcbvb_DISTMODE VBUCKET_DISTRIBUTION_TYPE;
+#define VBUCKET_DISTRIBUTION_VBUCKET LCBVB_DIST_VBUCKET
+#define VBUCKET_DISTRIBUTION_KETAMA LCBVB_DIST_KETAMA
+#define VBUCKET_NO_CHANGES LCBVB_NO_CHANGES
+#define VBUCKET_SERVERS_MODIFIED LCBVB_SERVERS_MODIFIED
+#define VBUCKET_MAP_MODIFIED LCVBVB_MAP_MODIFIED
+
+LIBCOUCHBASE_API int vbucket_config_parse(lcbvb_CONFIG*,vbucket_source_t,const char*);
+LIBCOUCHBASE_API const char *vbucket_get_error_message(lcbvb_CONFIG*);
+LIBCOUCHBASE_API lcbvb_CONFIG* vbucket_config_create(void);
+LIBCOUCHBASE_API void vbucket_config_destroy(lcbvb_CONFIG*);
+LIBCOUCHBASE_API int vbucket_config_get_num_replicas(lcbvb_CONFIG*);
+LIBCOUCHBASE_API int vbucket_config_get_num_vbuckets(lcbvb_CONFIG*);
+LIBCOUCHBASE_API int vbucket_config_get_num_servers(lcbvb_CONFIG*);
+LIBCOUCHBASE_API const char *vbucket_config_get_server(lcbvb_CONFIG*,int);
+LIBCOUCHBASE_API const char *vbucket_config_get_couch_api_base(lcbvb_CONFIG*,int);
+LIBCOUCHBASE_API const char *vbucket_config_get_rest_api_server(lcbvb_CONFIG*,int);
+LIBCOUCHBASE_API lcbvb_DISTMODE vbucket_config_get_distribution_type(lcbvb_CONFIG*);
+LIBCOUCHBASE_API int vbucket_map(lcbvb_CONFIG*,const void*,lcb_SIZE,int*,int*);
+LIBCOUCHBASE_API int vbucket_get_vbucket_by_key(lcbvb_CONFIG*,const void*,lcb_SIZE);
+LIBCOUCHBASE_API int vbucket_get_master(lcbvb_CONFIG*,int);
+LIBCOUCHBASE_API int vbucket_get_replica(lcbvb_CONFIG*,int,int);
+LIBCOUCHBASE_API lcbvb_CONFIGDIFF* vbucket_compare(lcbvb_CONFIG*,lcbvb_CONFIG*);
+LIBCOUCHBASE_API void vbucket_free_diff(lcbvb_CONFIGDIFF*);
+LIBCOUCHBASE_API int vbucket_config_get_revision(lcbvb_CONFIG*);
+LIBCOUCHBASE_API lcbvb_CHANGETYPE vbucket_what_changed(lcbvb_CONFIGDIFF *diff);
+LIBCOUCHBASE_API int vbucket_config_generate(lcbvb_CONFIG *vb, unsigned, unsigned, unsigned);
+
+
+#ifdef __cplusplus
+}
+#endif
+#endif