mt-libcouchbase 1.4.0

data/ext/libcouchbase/doc/cbcrc.markdown

@@ -0,0 +1,52 @@
+# cbcrc(4) - Configuration file for Couchbase command line tools
+
+## SYNOPSIS
+
+`~/.cbcrc`
+
+## DESCRIPTION
+
+cbcrc is an optional configuration file used to provide default values for the
+cbc(1) and cbc-pillowfight(1) utilities. It should be placed in
+
+Each entry in the cbcrc file is a line with a key-value pair in the following
+form:
+
+    # optional comments
+    key=value
+
+The keys may be specified in random order, and if you specify the same
+key multiple times the last value "wins". The following keys exists:
+
+* `connstr`:
+  This is the URI-like string used to connect to the cluster. Its format
+  consists of a _scheme_ followed by a list of hosts, an optional
+  bucket for the path and an optional `?` followed by key-value options.
+
+  Using custom REST API ports
+
+    http://localhost:9000,localhost:9001,localhost:9002
+
+  Using custom memcached ports:
+
+    couchbase://localhost:9100,localhost:9200,localhost:9300
+
+* `user`:
+    This is the user name used during authentication to your bucket
+
+* `password`:
+    This is the password used during authentication to your bucket
+
+* `timeout`:
+    The timeout value to use for the operations.
+
+## NOTES
+
+* You can generate such a file from the cbc(1) itself using the `write-config`
+  subcommand
+
+* Most other options can be specified within the connection string
+
+## SEE ALSO
+
+cbc(1), cbc-pillowfight(1)

data/ext/libcouchbase/doc/common-additional-options.markdown

@@ -0,0 +1,82 @@
+* `operation_timeout=SECONDS`:
+  Specify the operation timeout in seconds. This is the time the client will
+  wait for an operation to complete before timing it out. The default is `2.5`
+* `config_cache=PATH`:
+  Enables the client to make use of a file based configuration cache rather
+  than connecting for the bootstrap operation. If the file does not exist, the
+  client will first connect to the cluster and then cache the bootstrap information
+  in the file.
+* `truststorepath=PATH`:
+  The path to the server's SSL certificate. This is typically required for SSL
+  connectivity unless the certificate has already been added to the OpenSSL
+  installation on the system (only applicable with `couchbases://` scheme)
+* `certpath=PATH`:
+  The path to the server's SSL certificate. This is typically required for SSL
+  connectivity unless the certificate has already been added to the OpenSSL
+  installation on the system (only applicable with `couchbases://` scheme).
+  This also should contain client certificate when certificate authentication
+  used, and in this case other public certificates could be extracted into
+  `truststorepath` chain.
+* `keypath=PATH`:
+  The path to the client SSL private key. This is typically required for SSL
+  client certificate authentication. The certificate itself have to go first
+  in chain specified by `certpath` (only applicable with `couchbases://` scheme)
+* `ssl=no_verify`:
+  Temporarily disable certificate verification for SSL (only applicable with
+  `couchbases://` scheme). This should only be used for quickly debugging SSL
+  functionality.
+* `sasl_mech_force=MECHANISM`:
+  Force a specific _SASL_ mechanism to be used when performing the initial
+  connection. This should only need to be modified for debugging purposes.
+  The currently supported mechanisms are `PLAIN` and `CRAM-MD5`
+* `bootstrap_on=<both,http,cccp>`:
+  Specify the bootstrap protocol the client should use when attempting to connect
+  to the cluster. Options are: `cccp`: Bootstrap using the Memcached protocol
+  (supported on clusters 2.5 and greater); `http`: Bootstrap using the HTTP REST
+  protocol (supported on any cluster version); and `both`: First attempt bootstrap
+  over the Memcached protocol, and use the HTTP protocol if Memcached bootstrap fails.
+  The default is `both`
+
+* `enable_tracing=true/false`: Activate/deactivate end-to-end tracing.
+
+* `tracing_orphaned_queue_flush_interval=SECONDS`: Flush interval for orphaned
+  spans queue in default tracer. This is the time the tracer will wait between
+  repeated attempts to flush most recent orphaned spans.
+  Default value is 10 seconds.
+
+* `tracing_orphaned_queue_size=NUMBER`: Size of orphaned spans queue in default
+  tracer. Queues in default tracer has fixed size, and it will remove
+  information about older spans, when the limit will be reached before flushing
+  time.
+  Default value is 128.
+
+* `tracing_threshold_queue_flush_interval=SECONDS`: Flush interval for spans
+  with total time over threshold in default tracer. This is the time the tracer
+  will wait between repeated attempts to flush threshold queue.
+  Default value is 10 seconds.
+
+* `tracing_threshold_queue_size=NUMBER`: Size of threshold queue in default
+  tracer. Queues in default tracer has fixed size, and it will remove
+  information about older spans, when the limit will be reached before flushing
+  time.
+  Default value is 128.
+
+* `tracing_threshold_kv=SECONDS`: Minimum time for the tracing span of KV
+  service to be considered by threshold tracer.
+  Default value is 0.5 seconds.
+
+* `tracing_threshold_n1ql=SECONDS`: Minimum time for the tracing span of N1QL
+  service to be considered by threshold tracer.
+  Default value is 1 second.
+
+* `tracing_threshold_view=SECONDS`: Minimum time for the tracing span of VIEW
+  service to be considered by threshold tracer.
+  Default value is 1 second.
+
+* `tracing_threshold_fts=SECONDS`: Minimum time for the tracing span of FTS
+  service to be considered by threshold tracer.
+  Default value is 1 second.
+
+* `tracing_threshold_analytics=SECONDS`: Minimum time for the tracing span of
+  ANALYTICS service to be considered by threshold tracer.
+  Default value is 1 second.

data/ext/libcouchbase/doc/common-options.markdown

@@ -0,0 +1,71 @@
+* `-U`, `--spec`=_SPEC_:
+  A string describing the cluster to connect to. The string is in a URI-like syntax,
+  and may also contain other options. See the [EXAMPLES](#examples) section for information.
+  Typically such a URI will look like `couchbase://host1,host2,host3/bucket`.
+
+  The default for this option is `couchbase://localhost/default`
+
+* `-u`, `--username`=_USERNAME_:
+  Specify the _username_ for the bucket. Since Couchbase 5.x this is mandatory
+  switch, and it must specify the name of the user exisiting on cluster (read
+  more at "Security/Authorization" section of the server manual). For older servers
+  this field should be either left empty or set to the name of the bucket itself.
+
+* `-P`, `--password`=_PASSWORD_:
+* `-P -`, `--password=-`:
+  Specify the password for the bucket. As for servers before 5.x this was only
+  needed if the bucket is protected with a password. For cluster version after 5.x,
+  the password is mandatory, and should match the selected account (read more at
+  "Security/Authorization" section of the server manual).
+
+  Specifying the `-` as the password indicates that the program should prompt for the
+  password. You may also specify the password on the commandline, directly,
+  but is insecure as command line arguments are visible via commands such as `ps`.
+
+* `-T`, `--timings`:
+  Dump command timings at the end of execution. This will display a histogram
+  showing the latencies for the commands executed.
+
+* `-v`, `--verbose`:
+  Specify more information to standard error about what the client is doing. You may
+  specify this option multiple times for increased output detail.
+
+* `-D`, `--cparam`=OPTION=VALUE:
+  Provide additional client options. Acceptable options can also be placed
+  in the connection string, however this option is provided as a convenience.
+  This option may be specified multiple times, each time specifying a key=value
+  pair (for example, `-Doperation_timeout=10 -Dconfig_cache=/foo/bar/baz`).
+  See [ADDITIONAL OPTIONS](#additional-options) for more information
+
+* `-y`, `--compress`:
+  Enable compressing of documents. When the library is compiled with compression
+  support, this option will enable Snappy compression for outgoing data.
+  Incoming compressed data handled automatically regardless of this option.
+  Note, that because the compression support have to be negotiated with the
+  server, first packets might be sent uncompressed even when this switch
+  was specified. This is because the library might queue data commands before
+  socket connection has been established, and the library will negotiate
+  compression feature. If it is known that all server support compression
+  repeating the switch (like `-yy`) will force compression for all outgoing
+  mutations, even scheduled before establishing connection.
+
+* `--truststorepath`=_PATH_:
+  The path to the server's SSL certificate. This is typically required for SSL
+  connectivity unless the certificate has already been added to the OpenSSL
+  installation on the system (only applicable with `couchbases://` scheme)
+
+* `--certpath`=_PATH_:
+  The path to the server's SSL certificate. This is typically required for SSL
+  connectivity unless the certificate has already been added to the OpenSSL
+  installation on the system (only applicable with `couchbases://` scheme).
+  This also should contain client certificate when certificate authentication
+  used, and in this case other public certificates could be extracted into
+  `truststorepath` chain.
+
+* `--keypath`=_PATH_:
+  The path to the client SSL private key. This is typically required for SSL
+  client certificate authentication. The certificate itself have to go first
+  in chain specified by `certpath` (only applicable with `couchbases://` scheme)
+
+* `--dump`:
+  Dump verbose internal state after operations are done.

data/ext/libcouchbase/doc/environment.h

@@ -0,0 +1,93 @@
+/**
+ * @page lcb-env-vars-page Environment Variables
+ *
+ * @brief Environment variables controlling the behavior of the library
+ *
+ * @details
+ * While normally you would configure the library programmatically, there are
+ * some environment variables which may affect the library's behavior.
+ *
+ * Environment variables are intended to aid in debugging and otherwise modifying
+ * the library's behavior on a temporary basis. Typically this may be used to
+ * increase logging, or to modify/enable a feature which has deliberately been
+ * hidden from the normal API.
+ *
+ *
+ * @section lcb-env-vars Environment Variables
+ *
+ * @subsection LCB_IOPS_NAME
+ * Specify the name of the backend to load. This can be one of the built-in
+ * names, or it can be a path to a plugin which should be loaded dynamically.
+ *
+ * The built-in names are:
+ *
+ * * `libevent`
+ * * `libev`
+ * * `select`
+ * * `libuv`
+ * * `iocp` (Windows only)
+ *
+ * @committed
+ *
+ *
+ * @subsection LCB_IOPS_SYMBOL
+ * The symbol inside the shared object (specified as `LCB_IOPS_NAME`) that should
+ * contain the plugin initialization function. By default this is in the form of
+ * `libcouchbase_create_${NAME}_io_opts`
+ *
+ * @committed
+ *
+ * @subsection LCB_DLOPEN_DEBUG
+ *
+ * Print verbose information to the screen when attempting to log the plugins.
+ * This can help determine why a specific plugin is not being loaded
+ *
+ * @committed
+ *
+ * @subsection LCB_NO_HTTP
+ *
+ * Never bootstrap using the HTTP protocol.
+ * @volatile
+ *
+ * @subsection LCB_NO_CCCP
+ *
+ * Never bootstrap using the memcached protocol
+ * @volatile
+ *
+ * @subsection LCB_LOGLEVEL
+ *
+ * Enable the console logger and specify its verbosity level. The verbosity
+ * level is a number between 1-5 with higher numbers being more verbose
+ *
+ * @committed
+ *
+ * @subsection LCB_SSL_MODE
+ *
+ * Specify the _mode_ to use for SSL. Mode can either be `0` (for no SSL),
+ * `1` (for SSL with peer certificate verification), or `3` (for SSL
+ * with no certificate verification)
+ *
+ * @volatile
+ *
+ * @subsection LCB_SSL_CACERT
+ *
+ * Specify the path to the CA certificate to be used in order to validate
+ * the server's certificate
+ *
+ * @volatile
+ *
+ * @section LCB_INTERNAL_ENVVARS Internal Environment Variables
+ *
+ * @note
+ * This section will appear empty unless you have built internal documentation.
+ *
+ * @internal
+ *
+ *
+ * @subsection LCB_OPTIONS
+ *
+ * A string containing extra options for the connection string. These options
+ * are processed right after the existing connection string options (if any).
+ *
+ * @internal
+ */

data/ext/libcouchbase/doc/example/threads.c

@@ -0,0 +1,77 @@
+#include <pthread.h>
+#include <libcouchbase/couchbase.h>
+#include <libcouchbase/api3.h>
+
+typedef struct {
+    lcb_t instance;
+    pthread_mutex_t mutex;
+} my_CTX;
+
+/*
+ * This function uses the same instance between threads. A lock
+ * is required for every operation
+ */
+static void *
+thrfunc_locked(void *arg)
+{
+    my_CTX *ctx = arg;
+    lcb_CMDGET cmd = { 0 };
+    LCB_CMD_SET_KEY(&cmd, "Hello", strlen("Hello"));
+
+    pthread_mutex_lock(&ctx->mutex);
+    lcb_get3(ctx->instance, NULL, &cmd);
+    lcb_wait(ctx->instance);
+    pthread_mutex_unlock(&ctx->mutex);
+    return NULL;
+}
+
+/*
+ * This function uses an instance per thread. Since no other thread
+ * is using the instance, locking is not required
+ */
+static void *
+thrfunc_unlocked(void *arg)
+{
+    lcb_t instance;
+    lcb_create(&instance, NULL);
+    lcb_connect(instance);
+    lcb_wait(instance);
+    lcb_get_cmd_t cmd = { 0 }, *cmdp = &cmd;
+    lcb_get(instance, NULL, 1, &cmdp);
+    lcb_wait(instance);
+    lcb_destroy(instance);
+    return NULL;
+}
+
+int main(void)
+{
+    pthread_t thrs[10];
+    my_CTX ctx;
+    int ii;
+
+    lcb_create(&ctx.instance, NULL);
+    lcb_connect(ctx.instance);
+    lcb_wait(ctx.instance);
+    pthread_mutex_init(&ctx.mutex, NULL);
+
+    for (ii = 0; ii < 10; ii++) {
+        pthread_create(&thrs[ii], NULL, thrfunc_locked, &ctx);
+    }
+
+    for (ii = 0; ii < 10; ii++) {
+        void *ign;
+        pthread_join(thrs[ii], &ign);
+    }
+
+    lcb_destroy(ctx.instance);
+    pthread_mutex_destroy(&ctx.mutex);
+
+    for (ii = 0; ii < 10; ii++) {
+        pthread_create(&thrs[ii], NULL, thrfunc_unlocked, NULL);
+    }
+    for (ii = 0; ii < 10; ii++) {
+        void *ign;
+        pthread_join(thrs[ii], &ign);
+    }
+    return 0;
+}

data/ext/libcouchbase/doc/footer.html

@@ -0,0 +1,22 @@
+<!-- start footer part -->
+<!--BEGIN GENERATE_TREEVIEW-->
+<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
+  <ul>
+    $navpath
+    <li class="footer">
+    <b>Copyright 2010-2017, Couchbase Inc.</b>
+    $generatedby
+    <a href="http://www.doxygen.org/index.html">
+    <img class="footer" src="$relpath$doxygen.png" alt="doxygen"/></a> $doxygenversion </li>
+  </ul>
+</div>
+<!--END GENERATE_TREEVIEW-->
+<!--BEGIN !GENERATE_TREEVIEW-->
+<hr class="footer"/><address class="footer"><small>
+$generatedby &#160;<a href="http://www.doxygen.org/index.html">
+<img class="footer" src="$relpath$doxygen.png" alt="doxygen"/>
+</a> $doxygenversion
+</small></address>
+<!--END !GENERATE_TREEVIEW-->
+</body>
+</html>

data/ext/libcouchbase/doc/genman.sh

@@ -0,0 +1,25 @@
+#!/bin/sh
+set -e
+set -x
+
+# Run from the top level source directory
+OUTDIR=man
+SRCDIR=.
+
+MANPAGES="cbc cbc-pillowfight cbc-n1qlback cbc-subdoc"
+for page in $MANPAGES; do
+  ruby -e "puts ARGF.read.gsub('@@common-options.markdown@@', File.read('common-options.markdown'))" $SRCDIR/$page.markdown | \
+  ruby -e "puts ARGF.read.gsub('@@common-additional-options.markdown@@', File.read('common-additional-options.markdown'))" | \
+    ronn --pipe --roff  | sed 's/\\.\\.\\./\\[char46]\\[char46]\\[char46]/g' > $OUTDIR/$page.1
+done
+ronn --pipe --roff $SRCDIR/cbcrc.markdown | sed 's/\\.\\.\\./\\[char46]\\[char46]\\[char46]/g' > $OUTDIR/cbcrc.4
+
+MANLINKS="cat cp create observe flush hash lock unlock rm stats \
+version verbosity view admin bucket-create bucket-delete connstr \
+role-list user-list user-upsert user-delete ping n1ql mcflush \
+decr incr watch mcversion"
+
+for link in $MANLINKS; do
+    dest="$OUTDIR/cbc-${link}.1"
+    echo ".so man1/cbc.1" > "$dest"
+done

data/ext/libcouchbase/doc/header.html

@@ -0,0 +1,52 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
+<meta http-equiv="X-UA-Compatible" content="IE=9"/>
+<!--BEGIN PROJECT_NAME--><title>$projectname: $title</title><!--END PROJECT_NAME-->
+<!--BEGIN !PROJECT_NAME--><title>$title</title><!--END !PROJECT_NAME-->
+<link href="$relpath$tabs.css" rel="stylesheet" type="text/css"/>
+<script type="text/javascript" src="$relpath$jquery.js"></script>
+<script type="text/javascript" src="$relpath$dynsections.js"></script>
+$treeview
+$search
+$mathjax
+<link href="$relpath$style.css" rel="stylesheet" type="text/css" />
+</head>
+<body>
+<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
+
+<!--BEGIN TITLEAREA-->
+<div id="titlearea">
+<table cellspacing="0" cellpadding="0">
+ <tbody>
+ <tr style="height: 30px;">
+  <!--BEGIN PROJECT_LOGO-->
+  <td id="projectlogo"><img alt="Logo" src="$relpath$$projectlogo"/></td>
+  <!--END PROJECT_LOGO-->
+  <!--BEGIN PROJECT_NAME-->
+  <td style="padding-left: 0.5em;">
+   <div id="projectname">$projectname
+   <!--BEGIN PROJECT_NUMBER-->&#160;<span id="projectnumber">$projectnumber</span><!--END PROJECT_NUMBER-->
+   </div>
+   <!--BEGIN PROJECT_BRIEF--><div id="projectbrief">$projectbrief</div><!--END PROJECT_BRIEF-->
+  </td>
+  <!--END PROJECT_NAME-->
+  <!--BEGIN !PROJECT_NAME-->
+   <!--BEGIN PROJECT_BRIEF-->
+    <td style="padding-left: 0.5em;">
+    <div id="projectbrief">$projectbrief</div>
+    </td>
+   <!--END PROJECT_BRIEF-->
+  <!--END !PROJECT_NAME-->
+  <!--BEGIN DISABLE_INDEX-->
+   <!--BEGIN SEARCHENGINE-->
+   <td>$searchbox</td>
+   <!--END SEARCHENGINE-->
+  <!--END DISABLE_INDEX-->
+ </tr>
+ </tbody>
+</table>
+</div>
+<!--END TITLEAREA-->
+<!-- end header part -->

data/ext/libcouchbase/doc/intro.h

@@ -0,0 +1,130 @@
+/**
+ * @page intro_sec Introduction
+ *
+ * libcouchbase is an asynchronous library for connecting to a Couchbase
+ * server and performing data operations.
+ *
+ * This contains the API documentation for the library. The documentation
+ * consists of both _internal_ and _public_ interfaces.
+ *
+ * Using the library is comprised of these steps:
+ *
+ * 1. Create an instance (See lcb_create())
+ * 2. Install callbacks (See lcb_set_get_callback())
+ * 3. Schedule an operation (e.g. lcb_get())
+ * 4. Wait for the operation to complete (lcb_wait())
+ *
+ * _libcouchbase_ is an asynchronous library which means that operation
+ * results are passed to callbacks you define rather than being returned from
+ * functions.
+ *
+ * Callbacks are passed a `cookie` parameter which is a user-defined pointer
+ * (i.e. your own pointer which can be `NULL`) to associate a specific command
+ * with a specific callback invocation.
+ *
+ * For simple synchronous use, you will need to call lcb_wait() after each
+ * set of scheduled operations. During lcb_wait() the library will block for
+ * I/O and invoke your callbacks as the results for the operations arrive.
+ *
+ * For non-synchronous use cases you can integrate with a variety of event loops
+ * via the various plugins, or integrate one yourself via the `IOPS` API
+ * (see @ref lcb-io-plugin-api)
+ *
+ * Modifying the library's settings (for example, timeout settings) may be done
+ * via the lcb_cntl() interface (see @ref lcb-cntl-settings) or via some environment
+ * variables (see @ref lcb-env-vars)
+ *
+ *
+ *
+ * ## Using the headers and libraries
+ *
+ * Using the libcouchbase headers is simple. Simply:
+ * @code{.c}
+ * #include <libcouchbase/couchbase.h>
+ * @endcode
+ *
+ * into your application.
+ *
+ * To link, simply link against `libcouchbase` (e.g. `-lcouchbase`).
+ *
+ *
+ * See @ref lcb_attributes for interface stability taxonomy and @ref lcb_thrsafe
+ * for information on programming in threaded environments
+ *
+ *
+ *
+ * ## Minimal example usage
+ * @include example/minimal/minimal.c
+ *
+ * ## Configuring and Tuning the library
+ *
+ * The library may be configured either programmatically via lcb_cntl(),
+ * or via the environment (see @ref lcb-env-vars)
+ *
+ *
+ * ## Simple Usage Steps
+ *
+ * 1. Create an `lcb_t` handle. This is done via lcb_create()
+ * 2. Schedule the initial connection, this is done via lcb_connect()
+ * 3. Wait for the initial connection to complete, via lcb_wait()
+ * 4. Install the callbacks for retrieval and storage (lcb_set_get_callback(),
+ *    lcb_set_stor_callback()).
+ * 5. Set up a command structure for storing an item, i.e. @ref lcb_store_cmd_t.
+ * 6. Schedule the operation via lcb_store(). You will also likely want to
+ *    pass a `cookie` parameter along with it so that you can associate your
+ *    application's structures via the callback.
+ * 7. Invoke lcb_wait(). Your callback will be invoked with the result of
+ *    the storage operation.
+ *
+ *
+ *
+ *
+ * @internal
+ * ## Public vs Internal APIs
+ *
+ * The @ref lcb-public-api section is where you should begin browsing to develop
+ * with the library. Any sections not contained within the public API are
+ * internal and are provided to aid in developing new features and fixing bugs
+ * within the library itself.
+ *
+ * ## Internal Header Layouts
+ *
+ * The internal headers are organized like so:
+ *
+ * * <lcbio/lcbio.h> - I/O Core
+ * * <mc/mcreq.h> - Memcached packet codecs
+ * * <netbuf/netbuf.h> - Write buffer implementation
+ * * <rdb/rope.h> - Read buffer implementation
+ * * <mcserver/mcserver.h> - Memcached client I/O
+ * * <mcserver/negotiate.h> - Memcached client initial SASL handling
+ * * <bucketconfig/clconfig.h> - Couchbase cluster configuration retrieval
+ * * <packetutils.h> - Utility for response packets
+ * * <src/retryq.h> - Retry queue for failed packets
+ * * <src/internal.h> - Other internal functions not in the above categories
+ *
+ * In addition to these files, there are several non-core files which exist
+ * to provide simple utilities which are not specific to the library:
+ *
+ * * <list.h> - Double-linked list
+ * * <sllist.h>, <sllist-inl.h> - Single linked list
+ * * <genhash.h> - Hashtable
+ * * <hashset.h> - Set of unique elements
+ * * <hostlist.h> - Host/Port structures and lists
+ *
+ * @endinternal
+ *
+ * ## Prerequisite Knowledge
+ *
+ * libcouchbase is a cross platform C library used to interact with Couchbase
+ * Server. It is assumed that you know about:
+ *
+ * * Key-Value stores
+ * * The C language
+ * * Asynchronous and non-blocking programming.
+ *
+ * To develop with the I/O integration APIs, you will need to know about:
+ *
+ * * Socket APIs
+ * * Event loops
+ *
+ */