libcouchbase 1.0.4 → 1.1.0

data/ext/libcouchbase/example/minimal/minimal.c

@@ -54,9 +54,8 @@ op_callback(lcb_t instance, int cbtype, const lcb_RESPBASE *rb)
             fprintf(stderr, "FLAGS: 0x%x\n", rg->itmflags);
         }
     } else {
-        die(instance, lcb_strcbtype(rb->rc), rb->rc);
+        die(instance, lcb_strcbtype(cbtype), rb->rc);
     }
-    (void)instance;
 }
 
 int main(int argc, char *argv[])
@@ -70,14 +69,17 @@ int main(int argc, char *argv[])
     create_options.version = 3;
 
     if (argc < 2) {
-        fprintf(stderr, "Usage: %s couchbase://host/bucket [ password ]\n", argv[0]);
+        fprintf(stderr, "Usage: %s couchbase://host/bucket [ password [ username ] ]\n", argv[0]);
         exit(EXIT_FAILURE);
     }
 
     create_options.v.v3.connstr = argv[1];
-    if (argc >= 3) {
+    if (argc > 2) {
         create_options.v.v3.passwd = argv[2];
     }
+    if (argc > 3) {
+        create_options.v.v3.username = argv[3];
+    }
 
     err = lcb_create(&instance, &create_options);
     if (err != LCB_SUCCESS) {
@@ -114,7 +116,7 @@ int main(int argc, char *argv[])
     lcb_wait(instance);
 
     /* Now fetch the item back */
-    LCB_CMD_SET_KEY(&gcmd, "foo", strlen("foo"));
+    LCB_CMD_SET_KEY(&gcmd, "key", strlen("key"));
     err = lcb_get3(instance, NULL, &gcmd);
     if (err != LCB_SUCCESS) {
         die(instance, "Couldn't schedule retrieval operation", err);

data/ext/libcouchbase/example/observe/durability.c

@@ -0,0 +1,102 @@
+/* -*- Mode: C; tab-width: 4; c-basic-offset: 4; indent-tabs-mode: nil -*- */
+/*
+ *     Copyright 2017 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.
+ */
+
+/*
+ * BUILD:
+ *   cc -o durability durability.c -lcouchbase
+ *
+ * RUN:
+ *   ./durability [ CONNSTRING [ PASSWORD [ USERNAME ] ] ]
+ *
+ *   # use default durability check method
+ *   ./durability couchbase://localhost
+ *
+ *   # force durability check method based on sequence numbers
+ *   ./durability couchbase://localhost?fetch_mutation_tokens=true&dur_mutation_tokens=true
+ */
+#include <stdlib.h>
+#include <stdio.h>
+#include <string.h>
+#include <assert.h>
+#include <libcouchbase/couchbase.h>
+#include <libcouchbase/api3.h>
+
+#define fail(msg)                                                                                                      \
+    fprintf(stderr, "%s\n", msg);                                                                                      \
+    exit(EXIT_FAILURE)
+
+#define fail2(msg, err)                                                                                                \
+    fprintf(stderr, "%s\n", msg);                                                                                      \
+    fprintf(stderr, "Error was 0x%x (%s)\n", err, lcb_strerror(NULL, err));                                            \
+    exit(EXIT_FAILURE)
+
+static void store_callback(lcb_t instance, int cbtype, const lcb_RESPBASE *rb)
+{
+    const lcb_RESPSTOREDUR *resp = (const lcb_RESPSTOREDUR *)rb;
+    fprintf(stderr, "Got status of operation: 0x%02x, %s\n", resp->rc, lcb_strerror(NULL, resp->rc));
+    fprintf(stderr, "Stored: %s\n", resp->store_ok ? "true" : "false");
+    fprintf(stderr, "Number of roundtrips: %d\n", resp->dur_resp->nresponses);
+    fprintf(stderr, "In memory on master: %s\n", resp->dur_resp->exists_master ? "true" : "false");
+    fprintf(stderr, "Persisted on master: %s\n", resp->dur_resp->persisted_master ? "true" : "false");
+    fprintf(stderr, "Nodes have value replicated: %d\n", resp->dur_resp->nreplicated);
+    fprintf(stderr, "Nodes have value persisted (including master): %d\n", resp->dur_resp->npersisted);
+}
+
+int main(int argc, char *argv[])
+{
+    lcb_t instance;
+    lcb_error_t err;
+    lcb_CMDSTOREDUR cmd = {0};
+    struct lcb_create_st create_options = {0};
+    const char *key = "foo";
+    const char *value = "{\"val\":42}";
+
+    create_options.version = 3;
+    if (argc > 1) {
+        create_options.v.v3.connstr = argv[1];
+    }
+    if (argc > 2) {
+        create_options.v.v3.passwd = argv[2];
+    }
+    if (argc > 3) {
+        create_options.v.v3.username = argv[3];
+    }
+
+    if ((err = lcb_create(&instance, &create_options)) != LCB_SUCCESS) {
+        fail2("cannot create connection instance", err);
+    }
+    if ((err = lcb_connect(instance)) != LCB_SUCCESS) {
+        fail2("Couldn't schedule connection", err);
+    }
+    lcb_wait(instance);
+    if ((err = lcb_get_bootstrap_status(instance)) != LCB_SUCCESS) {
+        fail2("Couldn't get initial cluster configuration", err);
+    }
+    lcb_install_callback3(instance, LCB_CALLBACK_STOREDUR, store_callback);
+
+    LCB_CMD_SET_KEY(&cmd, key, strlen(key));
+    LCB_CMD_SET_VALUE(&cmd, value, strlen(value));
+    /* replicate and persist on all nodes */
+    cmd.replicate_to = -1;
+    cmd.persist_to = -1;
+    lcb_storedur3(instance, NULL, &cmd);
+
+    lcb_wait(instance);
+
+    lcb_destroy(instance);
+    return EXIT_SUCCESS;
+}

data/ext/libcouchbase/example/observe/observe.c

@@ -1,6 +1,6 @@
 /* -*- Mode: C; tab-width: 4; c-basic-offset: 4; indent-tabs-mode: nil -*- */
 /*
- *     Copyright 2013 Couchbase, Inc.
+ *     Copyright 2013-2017 Couchbase, Inc.
  *
  *   Licensed under the Apache License, Version 2.0 (the "License");
  *   you may not use this file except in compliance with the License.
@@ -28,11 +28,12 @@
 
 #define fail(msg) \
     fprintf(stderr, "%s\n", msg); \
-    exit(EXIT_FAILURE);
+    exit(EXIT_FAILURE)
 
 #define fail2(msg, err) \
     fprintf(stderr, "%s\n", msg); \
-    fprintf(stderr, "Error was 0x%x (%s)\n", err, lcb_strerror(NULL, err))
+    fprintf(stderr, "Error was 0x%x (%s)\n", err, lcb_strerror(NULL, err)); \
+    exit(EXIT_FAILURE)
 
 typedef struct {
     int master;
@@ -81,12 +82,24 @@ int main(int argc, char *argv[])
     lcb_MULTICMD_CTX *mctx = NULL;
     observe_info obs_info;
     unsigned nservers, ii;
+    struct lcb_create_st create_options = { 0 };
 
-    if (argc != 2) {
-        fail("requires key as argument");
+    if (argc < 2) {
+        fail("Requires key as argument\n"
+             "Usage: observe KEY [CONNSTRING [ PASSWORD [ USERNAME ] ] ]\n");
+    }
+    create_options.version = 3;
+    if (argc > 2) {
+        create_options.v.v3.connstr = argv[2];
+    }
+    if (argc > 3) {
+        create_options.v.v3.passwd = argv[3];
+    }
+    if (argc > 4) {
+        create_options.v.v3.username = argv[4];
     }
 
-    if ((err = lcb_create(&instance, NULL)) != LCB_SUCCESS) {
+    if ((err = lcb_create(&instance, &create_options)) != LCB_SUCCESS) {
         fail2("cannot create connection instance", err);
     }
     if ((err = lcb_connect(instance)) != LCB_SUCCESS) {

data/ext/libcouchbase/example/subdoc/subdoc-xattrs.c

@@ -124,8 +124,7 @@ static void n1qlrow_callback(lcb_t instance, int type, const lcb_RESPN1QL *resp)
     lcb_sched_leave(instance);
 }
 
-// #define DEFAULT_CONNSTR "couchbase://localhost/travel-sample"
-#define DEFAULT_CONNSTR "couchbase://192.168.1.194/travel-sample"
+#define DEFAULT_CONNSTR "couchbase://localhost/travel-sample"
 
 static lcb_t connect_as(char *username, char *password)
 {

data/ext/libcouchbase/include/libcouchbase/cntl-private.h

@@ -204,9 +204,6 @@ struct lcb_cntl_iops_info_st {
 #define LCB_CNTL_CONFIG_ALL_NODES 0x20
 
 /**
- * @internal
- *
- * @volatile
  * Reinitialize the instance using a connection string. Only options and
  * the hostlists are used from this string. The bucket in the string (if specified)
  * and any SSL options (i.e. `couchbases://` or `ssl=no_verify`) are ignored.
@@ -214,6 +211,7 @@ struct lcb_cntl_iops_info_st {
  *
  * This is the newer variant of @ref LCB_CNTL_CONFIG_ALL_NODES
  * @cntl_arg_setonly{const char *}
+ * @internal
  */
 #define LCB_CNTL_REINIT_CONNSTR 0x2B
 
@@ -290,7 +288,6 @@ struct lcb_cntl_rdballocfactory {
     lcb_RDBALLOCFACTORY factory;
 };
 /**
- * @volatile
  * Set the allocator factory used by libcouchbase. The allocator factory is
  * a function invoked with no arguments which yields a new rdb_ALLOCATOR
  * object. Currently the use and API of this object is considered internal
@@ -299,6 +296,7 @@ struct lcb_cntl_rdballocfactory {
  * Mode|Arg
  * ----|---
  * Set, Get | `lcb_cntl_rdballocfactory*`
+ * @volatile
  */
 #define LCB_CNTL_RDBALLOCFACTORY 0x27
 
@@ -319,37 +317,37 @@ typedef enum {
 
 
 /**
- * @volatile
  * @brief Persist heuristic vbucket information across updates.
  *
  * As of version 2.4.8 this option no longer has any effect, and vBucket
  * heuristics are always retained for a maximum of 20 seconds.
  * @cntl_arg_both{int*}
+ * @volatile
  */
 #define LCB_CNTL_VBGUESS_PERSIST 0x32
 
 /**
- * @volatile
  * This is a collection of various options which sacrifice data safety for
  * speed.
+ * @volatile
  */
 #define LCB_CNTL_UNSAFE_OPTIMIZE 0x33
 
 /**
- * @volatile
  * Disable or enable Nagle's algorithm. The default is to disable it, as it
  * will typically reduce latency. In general it is recommended not to touch
  * this setting. It is here mainly for debugging.
  *
  * Conventionally, the option to disable Nagle's algorithm is called "TCP_NODELAY",
  * thus if this value is one, Nagle is off, and vice versa.
+ * @volatile
  */
 #define LCB_CNTL_TCP_NODELAY 0x39
 
 /**
- * @volatile
  * Get the lcb_HISTOGRAM object for key-value timings
  * @cntl_arg_getonly{lcb_HISTOGRAM**}
+ * @volatile
  */
 #define LCB_CNTL_KVTIMINGS 0x3C
 

data/ext/libcouchbase/include/libcouchbase/cntl.h

@@ -1,6 +1,6 @@
 /* -*- Mode: C; tab-width: 4; c-basic-offset: 4; indent-tabs-mode: nil -*- */
 /*
- *     Copyright 2013 Couchbase, Inc.
+ *     Copyright 2017 Couchbase, Inc.
  *
  *   Licensed under the Apache License, Version 2.0 (the "License");
  *   you may not use this file except in compliance with the License.
@@ -73,14 +73,25 @@ extern "C" {
  * pointer types depending on whether the `mode` is retrieval or storage.
  *
  *
- * @section lcb-timeout-info Timeout Settings
+ * @section lcb-time-info Timeout and Time Value Settings
+ *
+ * There are various settings on the library that control behavior with
+ * respect to wall clock time.
  *
  * Timeout settings control how long the library will wait for a certain event
  * before proceeding to the next course of action (which may either be to try
  * a different operation or fail the current one, depending on the specific
  * timeout).
  *
- * Timeouts are specified in _microseconds_ stored within an `lcb_U32`.
+ * Other settings may configure how often the library proactively polls for
+ * a configuration update, retries various interally retried operations and
+ * so forth.
+ *
+ * Time values are specified in _microseconds_ stored within an `lcb_U32`.
+ *
+ * When specified as an argument to lcb_cntl_string() or through the connection
+ * string, it will be parsed from a string float value where the integer-part
+ * is in seconds and the fractional-part is in fractions of a second.
  *
  * Note that timeouts in libcouchbase are implemented via an event loop
  * scheduler. As such their accuracy and promptness is limited by how
@@ -133,7 +144,7 @@ extern "C" {
  *
  * @cntl_arg_both{lcbU32*}
  * @committed
- * @see lcb-timeout-info
+ * @see lcb-time-info
  */
 #define LCB_CNTL_OP_TIMEOUT             0x00
 
@@ -165,13 +176,27 @@ extern "C" {
  */
 #define LCB_CNTL_BUCKETNAME             0x30
 
+/**
+ * @brief Get the bucket type.
+ * This returns the bucket type - which is either of the following:
+ *
+ *  * LCB_BTYPE_UNSPEC
+ *  * LCB_BTYPE_COUCHBASE
+ *  * LCB_BTYPE_EPHEMERAL
+ *  * LCB_BTYPE_MEMCACHED
+ *
+ * @see https://developer.couchbase.com/documentation/server/current/architecture/core-data-access-buckets.html
+ *
+ * @cntl_arg_getonly{lcb_BTYPE*}
+ */
+#define LCB_CNTL_BUCKETTYPE             0x48
+
 /**
  * @brief Get the handle type.
  * This returns the handle type - which is either LCB_TYPE_CLUSTER or
  * LCB_TYPE_BUCKET
  *
  * @cntl_arg_getonly{lcb_type_t*}
- * @uncommitted
  */
 #define LCB_CNTL_HANDLETYPE             0x04
 
@@ -179,7 +204,6 @@ extern "C" {
  * Obtains the current cluster configuration from the client.
  *
  * @cntl_arg_getonly{lcbvb_CONFIG**}
- * @uncommitted
  */
 #define LCB_CNTL_VBCONFIG               0x05
 
@@ -222,13 +246,12 @@ typedef struct lcb_cntl_vbinfo_st {
  * update is requested again.
  *
  * @cntl_arg_both{lcb_SIZE*}
- * @uncommitted
  */
 #define LCB_CNTL_CONFERRTHRESH          0x0c
 
 /**
  * @brief Default timeout for lcb_durability_poll()
- * @ingroup lcb-timeout-info
+ * @ingroup lcb-time-info
  *
  * This is the time the client will
  * spend sending repeated probes to a given key's vBucket masters and replicas
@@ -248,7 +271,12 @@ typedef struct lcb_cntl_vbinfo_st {
  * @committed*/
 #define LCB_CNTL_DURABILITY_INTERVAL    0x0e
 
-/**@brief Timeout for non-views HTTP requests
+/**
+ * @brief Timeout for otherwise unspecified HTTP requests
+ *
+ * Examples of these kinds of HTTP requests might be cluster management,
+ * user management, etc.
+ *
  * @cntl_arg_both{lcb_U32*}
  * @committed*/
 #define LCB_CNTL_HTTP_TIMEOUT           0x0f
@@ -323,7 +351,6 @@ typedef struct lcb_cntl_vbinfo_st {
  * libcouchbase API, after which it may have been freed.
  *
  * @cntl_arg_get_and_set{char**, char*}
- * @uncommitted
  */
 #define LCB_CNTL_FORCE_SASL_MECH 0x16
 
@@ -360,7 +387,6 @@ struct lcb_logprocs_st;
 /**
  * @brief Logger callback
  *
- * @uncommitted
  *
  * This callback is invoked for each logging message emitted
  * @param procs the logging structure provided
@@ -378,7 +404,7 @@ typedef void (*lcb_logging_callback)(struct lcb_logprocs_st *procs,
 
 /**
  * @brief Logging context
- * @uncommitted
+ * @volatile
  *
  * This structure defines the logging handlers. Currently there is only
  * a single field defined which is the default callback for the loggers.
@@ -415,13 +441,14 @@ typedef struct lcb_logprocs_st {
  *
  * @cntl_arg_both{lcb_U32*}
  * @see LCB_CNTL_CONFERRTHRESH
- * @uncommitted
  */
 #define LCB_CNTL_CONFDELAY_THRESH 0x19
 
-/**@brief Get the transport used to fetch cluster configuration.
+/**
+ * @brief Get the transport used to fetch cluster configuration.
  * @cntl_arg_getonly{lcb_config_transport_t*}
- * @uncommitted*/
+ * @uncommitted
+ */
 #define LCB_CNTL_CONFIG_TRANSPORT 0x1A
 
 /**
@@ -468,19 +495,22 @@ typedef struct lcb_logprocs_st {
  */
 #define LCB_CNTL_HTCONFIG_IDLE_TIMEOUT 0x1C
 
-/**@brief Get the current SCM changeset for the library binary
+/**
+ * @brief Get the current SCM changeset for the library binary
  * @cntl_arg_getonly{char**}
- * @committed*/
+ */
 #define LCB_CNTL_CHANGESET 0x1F
 
 /**
- * @brief file used for the configuration cache.
+ * @brief File used for the configuration cache.
  *
  * The configuration
  * cache allows to bootstrap from a cluster without using the initial
  * bootstrap connection, considerably reducing latency. If the file passed
  * does not exist, the normal bootstrap process is performed and the file
- * is written to with the current information.
+ * is written to with the current information.  File will be updated as
+ * the configuration in the cluster changes.  Multiple instances may race
+ * to update the file, and that is the intended behavior.
  *
  * @note The leading directories for the file must exist, otherwise the file
  * will never be created.
@@ -529,12 +559,14 @@ typedef enum {
  * @see LCB_CNTL_SSL_MODE
  */
 #define LCB_CNTL_SSL_CERT 0x23
-/* For back compat */
+/**
+ * Alias for @ref LCB_CNTL_SSL_CERT for backward compatibility.
+ * @deprecated
+ */
 #define LCB_CNTL_SSL_CACERT LCB_CNTL_SSL_CERT
 
 /**
- * @brief
- * Select retry mode to manipulate
+ * @brief Select retry mode to manipulate
  */
 typedef enum {
     LCB_RETRY_ON_TOPOCHANGE = 0, /**< Select retry for topology */
@@ -577,8 +609,10 @@ typedef enum {
  */
 #define LCB_RETRYOPT_CREATE(mode, policy) (((mode) << 16) | policy)
 
-#define LCB_RETRYOPT_GETMODE(u) (u) >> 16
-#define LCB_RETRYOPT_GETPOLICY(u) (u) & 0xffff
+/** Get mode from retry setting value */
+#define LCB_RETRYOPT_GETMODE(u) ((u) >> 16)
+/** Get policy from retry setting value */
+#define LCB_RETRYOPT_GETPOLICY(u) ((u)&0xffff)
 
 /**
  * @volatile
@@ -637,12 +671,9 @@ typedef enum {
 } lcb_HTCONFIG_URLTYPE;
 
 /**
- * @volatile - Primarily here to support tests and buggy HTTP servers/proxies
- * which do not like to maintain a connection upon receipt of a 404.
- *
  * @brief Set the URL selection mode.
  *
- * The URL type can be a mask of the lcb_HTCONFIG_URLTYPE constants which
+ * The URL type can be a mask of the #lcb_HTCONFIG_URLTYPE constants which
  * indicate which URLs the HTTP provider should use.
  *
  * The default is to use the `25PLUS` URI first, and fallback on the compat uri
@@ -654,11 +685,13 @@ typedef enum {
  * This setting is only used when CCCP is disabled. This will typically be for
  * older clusters or for memcached buckets.
  * @cntl_arg_both{`int*` (value is one of @ref lcb_HTCONFIG_URLTYPE)}
+
+ * @volatile Primarily here to support tests and buggy HTTP servers/proxies
+ * which do not like to maintain a connection upon receipt of a 404.
  */
 #define LCB_CNTL_HTCONFIG_URLTYPE 0x25
 
 /**
- * @volatile
  * Determines whether to run the event loop internally within lcb_destroy()
  * until no more I/O resources remain for the library. This is usually only
  * necessary if you are creating a lot of instances and/or are using memory
@@ -666,12 +699,11 @@ typedef enum {
  *
  * @cntl_arg_both{`int*` (as a boolean)}
  * @see lcb_destroy_async() and lcb_set_destroy_callback()
+ * @volatile
  */
 #define LCB_CNTL_SYNCDESTROY 0x28
 
 /**
- * @committed
- *
  * Sets the logging level for the console logger. If a logger is already
  * initialized (either from the environment, or via lcb_cntl_logger() then
  * this operation does nothing.
@@ -681,8 +713,8 @@ typedef enum {
  * it from the environment.
  *
  * The argument passed to lcb_cntl() is an integer of 0 until
- * `LCB_LOGLEVEL_MAX`, though the actual type is of `lcb_U32` rather than
- * an enum type.
+ * `LCB_LOG_MAX`, though the actual type is of `lcb_U32` rather than
+ * an enum type #lcb_log_severity_t.
  *
  * @cntl_arg_setonly{const lcb_U32 *}
  * @see LCB_CNTL_LOGGER
@@ -690,7 +722,6 @@ typedef enum {
 #define LCB_CNTL_CONLOGGER_LEVEL 0x29
 
 /**
- * @uncommitted
  *
  * Sets the output file (as a `FILE*`) for the console logger. Note that
  * any existing file pointer will be cleared (but not `fclose()`d.
@@ -710,8 +741,6 @@ typedef enum {
 #define LCB_CNTL_CONLOGGER_FP 0x3B
 
 /**
- * @committed
- *
  * Sets the behavior for reporting network errors. By default network errors
  * are returned as `LCB_NETWORK_ERROR` return codes for compatibility reasons.
  * More detailed error codes may be available by enabling this option which will
@@ -726,7 +755,6 @@ typedef enum {
 #define LCB_CNTL_DETAILED_ERRCODES 0x2A
 
 /**
- * @uncommitted
  *
  * Sets the interval at which the retry queue will attempt to resend a failed
  * operation. When an operation fails and the retry policy (see
@@ -744,7 +772,6 @@ typedef enum {
 #define LCB_CNTL_RETRY_INTERVAL 0x2C
 
 /**
- * @uncommitted
  *
  * When an operation has been retried more than once and it has still not
  * succeeded, the library will attempt to back off for the operation by
@@ -756,7 +783,6 @@ typedef enum {
 #define LCB_CNTL_RETRY_BACKOFF 0x2D
 
 /**
- * @volatile
  * Whether commands are retried immediately upon receipt of not-my-vbucket
  * replies.
  *
@@ -766,22 +792,22 @@ typedef enum {
  * and @ref LCB_CNTL_RETRY_BACKOFF settings. Disabling this setting will
  * restore the older behavior. This may be used in case there are problems
  * with the default heuristic/retry algorithm.
+ *
+ * @volatile
  */
 #define LCB_CNTL_RETRY_NMV_IMM 0x37
 
 /**
- * @volatile
- *
  * Set the maximum pool size for pooled http (view request) sockets. This should
  * be set to 1 (the default) unless you plan to execute concurrent view requests.
  * You may set this to 0 to disable pooling
  *
  * @cntl_arg_both{lcb_SIZE}
+ * @volatile
  */
 #define LCB_CNTL_HTTP_POOLSIZE 0x2E
 
 /**
- * @uncomitted
  * Determine whether or not a new configuration should be received when an error
  * is received over the HTTP API (i.e. via lcb_make_http_request().
  *
@@ -789,24 +815,24 @@ typedef enum {
  * expectedly issuing a lot of requests which may result in an error.
  *
  * @cntl_arg_both{int (as boolean)}
+ * @uncommitted
  */
 #define LCB_CNTL_HTTP_REFRESH_CONFIG_ON_ERROR 0x2F
 
 /**
- * @volatile
  * Set the behavior of the lcb_sched_leave() API call. By default the
  * lcb_sched_leave() will also set up the necessary requirements for flushing
  * to the network. If this option is off then an explicit call to
  * lcb_sched_flush() must be performed instead.
  *
  * @cntl_arg_both{int (as boolean)}
+ * @volatile
  */
 #define LCB_CNTL_SCHED_IMPLICIT_FLUSH 0x31
 
 /**
- * @volatile
  *
- * Allow the server to return an additional 16 bytes of data for each
+ * Request the server to return an additional 16 bytes of data for each
  * mutation operation. This extra information may help with more reliable
  * durability polling, but will also increase the size of the response packet.
  *
@@ -819,8 +845,6 @@ typedef enum {
 #define LCB_CNTL_FETCH_MUTATION_TOKENS 0x34
 
 /**
- * @volatile
- *
  * This setting determines whether the lcb_durability_poll() function will
  * transparently attempt to use mutation token functionality (rather than checking
  * the CAS). This option is most useful for older code which does
@@ -836,24 +860,23 @@ typedef enum {
  * function.
  *
  * @cntl_arg_both{int (as boolean)}
+ * @volatile
  */
 #define LCB_CNTL_DURABILITY_MUTATION_TOKENS 0x35
 
 /**
- * @volatile
- *
  * This read-only property determines if the mutation token mechanism is supported
  * on the cluster itself. This will only be accurate once a single operation
  * has been performed on the cluster - or in other words, once a connection
  * to a data node has been established for the purposes of normal operations.
  *
  * @cntl_arg_getonly{int (as boolean)}
+ * @uncommitted
  */
 #define LCB_CNTL_MUTATION_TOKENS_SUPPORTED 0x38
 
 
 /**
- * @uncommitted
  * This setting determines if calls to lcb_wait() and lcb_wait3() will reset
  * the timeout of pending operations to the time that lcb_wait() was called,
  * rather than having the operation maintain the time of the call which
@@ -862,21 +885,21 @@ typedef enum {
  * avoid prematurely having operations time out.
  *
  * @cntl_arg_both{int (as boolean)}
+ * @uncommitted
  *
  * Use `"readj_wait_tmo"` for the string version
  */
 #define LCB_CNTL_RESET_TIMEOUT_ON_WAIT 0x3A
 
 /**
- * @volatile
  * Clears the internal prepared statement cache for N1QL
  *
  * This does not take any arguments, and is valid only on @ref LCB_CNTL_SET
+ * @uncommitted
  */
 #define LCB_CNTL_N1QL_CLEARACHE 0x3E
 
 /**
- * @committed
  * Sets additional text for negotiation. This allows wrappers or applications
  * to add additional identifying information which can then be seen in the
  * server logs.
@@ -902,12 +925,11 @@ typedef const char *lcb_BUCKETCRED[2];
 /**
  * Set the amount of time the client should wait before retrying a
  * not-my-vbucket response packet. The default is 100ms. The value should
- * be specified in microseconds
- *
- * @committed
- * @cntl_arg_both{lcb_U32*}
+ * be specified in microseconds.
  *
  * Use `"retry_nmv_interval"` with lcb_cntl_string()
+ *
+ * @cntl_arg_both{lcb_U32*}
  */
 #define LCB_CNTL_RETRY_NMV_INTERVAL 0x41
 
@@ -919,7 +941,6 @@ typedef const char *lcb_BUCKETCRED[2];
  * @note This setting only works for event-style I/O plugins. This means it
  * has no effect on completion style plugins such as libuv or Windows IOCP
  *
- * @committed
  * @cntl_arg_both{lcb_U32*}
  */
 #define LCB_CNTL_READ_CHUNKSIZE 0x42
@@ -930,7 +951,6 @@ typedef const char *lcb_BUCKETCRED[2];
  *
  * Use `enable_errmap` in the connection string
  *
- * @volatile
  * @cntl_arg_both{int* (as boolean)}
  */
 #define LCB_CNTL_ENABLE_ERRMAP 0x43
@@ -945,7 +965,6 @@ typedef const char *lcb_BUCKETCRED[2];
  *
  * Use `select_bucket` in the connection string
  *
- * @volatile
  * @cntl_arg_both{int* (as boolean)}
  */
 #define LCB_CNTL_SELECT_BUCKET 0x44
@@ -956,7 +975,6 @@ typedef const char *lcb_BUCKETCRED[2];
  *
  * The keepalive interval will be set to the operating system default.
  *
- * @committed
  * @cntl_arg_both{int* (as boolean)}
  */
 #define LCB_CNTL_TCP_KEEPALIVE 0x45
@@ -970,7 +988,6 @@ typedef const char *lcb_BUCKETCRED[2];
  * This option facilitates 'fast failover' - in that the client can preemptively
  * check for any cluster topology updates before encountering an error.
  *
- * @volatile
  * @cntl_arg_both{lcb_U32*}
  *
  * The value for this option is a time value. See the top of this header
@@ -998,15 +1015,18 @@ typedef const char *lcb_BUCKETCRED[2];
  * servers don't understand anyway). To disable the sending of hello, set this
  * value to false.
  *
- * @uncommitted
  * @cntl_arg_both{int* (as boolean)}
+ * @committed
  *
  * You can also use `send_hello=false` in the connection string.
  */
 #define LCB_CNTL_SEND_HELLO 0x47
 
-/** This is not a command, but rather an indicator of the last item */
-#define LCB_CNTL__MAX                    0x48
+/**
+ * This is not a command, but rather an indicator of the last item.
+ * @internal
+ */
+#define LCB_CNTL__MAX                    0x49
 /**@}*/
 
 #ifdef __cplusplus