Chapter 12
C API

12.1 Client Library

The HyperDex Client library, libhyperdex-client is the de facto way to access a HyperDex cluster for storing and retrieving data. All data-store operations are provided by the this library.

Until release 1.0.rc5, libhyperdex-client was called libhyperclient. It was changed to be more consistent with the naming of other HyperDex C libraries.

12.1.1 Building the HyperDex C Binding

The HyperDex C Binding is automatically built and installed via the normal HyperDex build and install process. You can ensure that the client is always built by providing the --enable-client option to ./configure like so:

  % ./configure --enable-client

12.1.2 Compiling and Linking Your Application

Unless otherwise noted, all Client operations are defined in the hyperdex/client.h include. You can include this in your own program with:

  #include <hyperdex/client.h>

To link against libhyperdex-client, provide the -lhyperdex-client option at link time:

  % cc -o output input.c -I/path/to/hyperdex/include -L/path/to/hyperdex/lib -lhyperdex-client

HyperDex provides support for the automatically determining the compiler and linker flags for libhyperdex-client. First, ensure the pkg-config program is installed, and then run:

  % pkg-config --cflags hyperdex-client -I/usr/local/include
  % pkg-config --libs hyperdex-client -L/usr/local/lib -lhyperdex-client

The first command outputs the compiler flags necessary to include the hyperdex/client.h file, while the second command outputs the flags necessary for linking against libhyperdex-client.

To put it all together, you can compile your application with:

  % cc -o output input.c pkg-config --cflags --libs hyperdex-client

For more information about pkg-config, see the pkg-config documentation.

12.1.3 Hello World

The following is a minimal application that stores the value ”Hello World” and then immediately retrieves the value:

  /* WARNING:  This code omits all error checking and is for illustration only */
  /* HyperDex Includes */

  #include <hyperdex/client.h>
  int
  main(int argc, const char* argv[])
  {
      struct hyperdex_client* client = NULL;

      struct hyperdex_client_attribute attr;
      struct hyperdex_client_attribute* attrs;

      size_t attrs_sz = 0;
      int64_t op_id;
      enum hyperdex_client_returncode op_status;

      int64_t loop_id;
      enum hyperdex_client_returncode loop_status;
      size_t i;
  

      client = hyperdex_client_create("127.0.0.1", 1982);
  
      attr.attr = "v";
      attr.value = "Hello World!";

      attr.value_sz = strlen(attr.value);
      attr.datatype = HYPERDATATYPE_STRING;
  
      /* perform the "put" */

      op_id = hyperdex_client_put(client, "kv", "some key", 8,
                                  &attr, 1, &op_status);

      loop_id = hyperdex_client_loop(client, -1, &loop_status);
      printf("put \"Hello World!\"\n");

  
      /* perform the "get" */
      op_id = hyperdex_client_get(client, "kv", "some key", 8,

                                  &op_status, &attrs, &attrs_sz);

      loop_id = hyperdex_client_loop(client, -1, &loop_status);
      printf("get done\n");
  

      for (i = 0; i < attrs_sz; ++i)
      {
          printf("got attribute \"%s\" = \"%.*s\"\n",

                 attrs[i].attr, attrs[i].value_sz, attrs[i].value);
      }
  

      hyperdex_client_destroy_attrs(attrs, attrs_sz);
      hyperdex_client_destroy(client);
      return EXIT_SUCCESS;
  }

You can compile and run this example with:

  % cc -o hello-world hello-world.c pkg-config --cflags --libs hyperdex-client
  % ./hello-world
  put "Hello World!"
  get done
  got attribute "v" = "Hello World!"

Right away, there are several points worth noting in this example:

12.1.4 Asynchronous Patterns

All operations are issued asynchronously, that is, the operation’s start is decoupled from its completion, and it is up to the application to wait for its completion.

The C API provides a unified, event-loop-like interface for polling events for their completion. An application can issue any number of operations, and poll for their completion using the hyperdex_client_loop call. This provides you with several advantages unavailable in any other distributed key-value store:

Of course, applications do not need to embrace this asynchronous design pattern. It’s always possible to use the library in a synchronous manner by immediately following every operation with a call to hyperdex_client_loop.

Applications that do embrace this asynchronous design pattern will have a certain structure. Specifically:

Finally, it’s important to realize that calling hyperdex_client_loop is necessary to complete operations. An operation’s outcome is not determined until the application calls hyperdex_client_loop. Do not simply issue hyperdex_client_put operations (or similar) and assume that the operations complete because there is no guarantee that they will do so.

12.1.5 Creating a Client

A HyperDex client is encapsulated within the incomplete struct hyperdex_client type. This type is created by the HyperDex client library, and should only be freed using the provided method.

  struct hyperdex_client*
  hyperdex_client_create(const char* coordinator, uint16_t port);

Create a new client instance. This call allocates and initializes local structures. If allocation or initialization fail, the call will return NULL and set errno appropriately. This call does not establish the connection to the coordinator; that will be established and maintained automatically by other calls made with this client instance.

Parameters:

coordinator
A C-string containing IP address or hostname of the coordinator.
port
The port number for the coordinator.
  void
  hyperdex_client_destroy(struct hyperdex_client* client);

Destroy a previously instantiated client, and release all associated resources. This call always succeeds.

Parameters:

client
A previously created client instance.

12.1.6 Data Structures

HyperDex natively supports a variety of data structures. This section describes the available data structures and their encoding within C. HyperDex encodes as a byte string all data structures passed between the application and HyperDex. This format of this byte string varies according to its type. In this section, we’ll describe the format of data structures, and provide an API for serializing to and from the prescribed format. All APIs discussed in this section are provided by libhyperdex-client.

12.1.6.1 enum hyperdatatype

The enum hyperdatatype is used to represent the type of a byte string to HyperDex. Whenever a structure accepts a byte string as a value, it will typically accept an enum hyperdatatype to convey the type of the string. Primitive Data Types  Primitive data types are the basic data types of HyperDex. Applications may use these primitives as the key and dimensions of hyperspaces within HyperDex.

HYPERDATATYPE_STRING
A byte string.
HYPERDATATYPE_INT64
A 64-bit signed integer.
HYPERDATATYPE_FLOAT
A 64-bit floating point value.
Container Data Types  Container data types contain a collection of primitive data types. Container data types cannot be used as the key or dimensions of the hyperspace. There are three container types available within HyperDex:
Lists
A list contains elements of one primitive type. The order of elements in a list is preserved, and it’s possible for duplicate elements to exist.
Sets
A set contains elements of one primitive type. Each element exists in the set at most once. Although the implementation enforces an order on the set for efficiency purposes, set operations are agnostic to the order of the included elements.
Maps
A map contains key-value pairs of elements, where the key and value may be of different types. Each key is unique and has an associated value. Maps also offer the ability to perform most primitive operations on the values within the map.
Each of these containers may be instantiated with a primitive data type as the contained elements. In total, HyperDex supports all of the following container data types:
HYPERDATATYPE_LIST_STRING
A list of strings.
HYPERDATATYPE_LIST_INT64
A list of integers.
HYPERDATATYPE_LIST_FLOAT
A list of floats.
HYPERDATATYPE_SET_STRING
A set of strings.
HYPERDATATYPE_SET_INT64
A set of integers.
HYPERDATATYPE_SET_FLOAT
A set of floats.
HYPERDATATYPE_MAP_STRING_STRING
A map from strings to strings.
HYPERDATATYPE_MAP_STRING_INT64
A map from strings to integers.
HYPERDATATYPE_MAP_STRING_FLOAT
A map from strings to floats.
HYPERDATATYPE_MAP_INT64_STRING
A map from integers to strings.
HYPERDATATYPE_MAP_INT64_INT64
A map from integers to integers.
HYPERDATATYPE_MAP_INT64_FLOAT
A map from integers to floats.
HYPERDATATYPE_MAP_FLOAT_STRING
A map from floats to strings.
HYPERDATATYPE_MAP_FLOAT_INT64
A map from floats to integers.
HYPERDATATYPE_MAP_FLOAT_FLOAT
A map from floats to floats.

The following data types are defined as well, and are generally only of interest to HyperDex developers and those who are writing client bindings:

HYPERDATATYPE_LIST_GENERIC
A list whose element type is unspecified.
HYPERDATATYPE_SET_GENERIC
A set whose element type is unspecified.
HYPERDATATYPE_MAP_GENERIC
A map whose key/value types are unspecified.
HYPERDATATYPE_MAP_STRING_KEYONLY
A map whose key is a string and whose value is unspecified.
HYPERDATATYPE_MAP_INT64_KEYONLY
A map whose key is an integer and whose value type is unspecified.
HYPERDATATYPE_MAP_FLOAT_KEYONLY
A map whose key is a float and whose value type is unspecified.
HYPERDATATYPE_GARBAGE
A reserved constant never used within HyperDex.
12.1.6.2 Bytestring Format

The format of the data structures is defined to be the same on all platforms.

For each format, Python-like psuedocode is provided that shows example encodings. string format  A string is an 8-bit byte string. HyperDex is agnostic to the contents of the string, and it may contain any bytes, including
x00. By convention, the trailing NULL should be omitted for C-strings to ensure interoperability across languages. For example:

  >>> encode_string(’Hello\x00World!’)
  b’Hello\x00World!’
int format  Integers are encoded as signed 8-byte little-endian integers. For example:
  >>> encode_int(1)
  b\x01\x00\x00\x00\x00\x00\x00\x00
  >>> encode_int(-1)
  b\xff\xff\xff\xff\xff\xff\xff\xff
  >>> encode_int(0xdeadbeef)
  b\xef\xbe\xad\xde\x00\x00\x00\x00
float format  Floats are encoded as IEEE 754 binary64 values in little-endian format. For example:
  >>> encode_double(0)
  b\x00\x00\x00\x00\x00\x00\x00\x00
  >>> encode_double(3.1415)
  b’o\x12\x83\xc0\xca!\t@’
list(string) format  Lists of strings are encoded by concatenating the encoding of each string, prefixed by an unsigned 4-byte little endian integer indicating the length of the string. For example:
  >>> encode_list_string([])
  b’’
  >>> encode_list_string([’hello’, ’world’])
  b\x05\x00\x00\x00hello\x05\x00\x00\x00world’
list(int) format  Lists of integers are encoded by concatenating the encoded form of each integer. For example:
  >>> encode_list_int([])
  b’’
  >>> encode_list_int([1, -1, 0xdeadbeef])
  b\x01\x00\x00\x00\x00\x00\x00\x00 \
  b\xff\xff\xff\xff\xff\xff\xff\xff \
  b\xef\xbe\xad\xde\x00\x00\x00\x00
list(floats) format  Lists of floats are encoded by concatenating the encoded form of each float. For example:
  >>> encode_list_float([])
  b’’
  >>> encode_list_float([0, 3.1415])
  b\x00\x00\x00\x00\x00\x00\x00\x00 \
  b’o\x12\x83\xc0\xca!\t@’
set(string) format  Sets of strings are encoded by concatenating the encoding of each string in sorted order, where each string is prefixed by an unsigned 4-byte little endian integer indicating the length of the string. For example:
  >>> encode_set_string([])
  b’’
  >>> encode_set_string([’world’, ’hello’])
  b\x05\x00\x00\x00hello\x05\x00\x00\x00world’
set(int) format  Sets of integers are encoded by concatenating the encoded form of each integer in sorted order. For example:
  >>> encode_set_int([])
  b’’
  >>> encode_set_int([1, -1, 0xdeadbeef])
  b\xff\xff\xff\xff\xff\xff\xff\xff \
  b\x01\x00\x00\x00\x00\x00\x00\x00 \
  b\xef\xbe\xad\xde\x00\x00\x00\x00
set(float) format  Sets of floats are encoded by concatenating the encoded form of each float in sorted order. For example:
  >>> encode_set_float([])
  b’’
  >>> encode_set_float([3.1415, 0])
  b\x00\x00\x00\x00\x00\x00\x00\x00 \
  b’o\x12\x83\xc0\xca!\t@’
map(string, string) format  Maps from strings to strings are formed by encoding the individual elements, each prefixed by an unsigned 4-byte little endian integer indicating their length. The pairs of elements are stored in sorted order according to the first element of the pair (the map’s key). For example:
  >>> encode_map_string_string({})
  b’’
  >>> encode_map_string_string({’hello’: ’world’,
  ...                           ’map key’: ’map val’,
  ...                           ’map’, ’encoding’})
  b\x05\x00\x00\x00hello\x05\x00\x00\x00world’ \
  b\x03\x00\x00\x00map\x08\x00\x00\x00encoding’ \
  b\x07\x00\x00\x00map key\x07\x00\x00\x00map val’
map(string, int) format  Maps from strings to ints are formed by encoding the individual elements, where keys are prefixed by an unsigned 4-byte little endian integer indicating their length. The pairs of elements are stored in sorted order according to the first element of the pair (the map’s key). For example:
  >>> encode_map_string_int({})
  b’’
  >>> encode_map_string_int({’world’: -1,
  ...                        ’hello’: 1})
  b\x05\x00\x00\x00hello\x01\x00\x00\x00\x00\x00\x00\x00 \
  b\x05\x00\x00\x00world\xff\xff\xff\xff\xff\xff\xff\xff
map(string, float) format  Maps from strings to ints are formed by encoding the individual elements, where keys are prefixed by an unsigned 4-byte little endian integer indicating their length. The pairs of elements are stored in sorted order according to the first element of the pair (the map’s key). For example:
  >>> encode_map_string_float({})
  b’’
  >>> encode_map_string_float({’zero’: 0,
  ...                          ’pi’: 3.1415})
  b\x02\x00\x00\x00pio\x12\x83\xc0\xca!\t@’ \
  b\x04\x00\x00\x00zero\x00\x00\x00\x00\x00\x00\x00\x00
map(int, string) format  Maps from ints to strings are formed by encoding the individual elements, where values are prefixed by an unsigned 4-byte little endian integer indicating their length. The pairs of elements are stored in sorted order according to the first element of the pair (the map’s key). For example:
  >>> encode_map_int_string({})
  b’’
  >>> encode_map_int_string({1: ’hello’,
  ...                        -1: ’world’})
  b\xff\xff\xff\xff\xff\xff\xff\xff\x05\x00\x00\x00world’ \
  b\x01\x00\x00\x00\x00\x00\x00\x00\x05\x00\x00\x00hello’
map(int, int) format  Maps from ints to ints are formed by encoding the individual elements. The pairs of elements are stored in sorted order according to the first element of the pair (the map’s key). For example:
  >>> encode_map_int_int({})
  b’’
  >>> encode_map_int_int({1: 0xdeadbeef,
  ...                     -1: 0x1eaff00d})
  b\xff\xff\xff\xff\xff\xff\xff\xff\x0d\xf0\xaf\x1e\x00\x00\x00\x00 \
  b\x01\x00\x00\x00\x00\x00\x00\x00\xef\xbe\xad\xde\x00\x00\x00\x00
map(int, float) format  Maps from ints to floats are formed by encoding the individual elements. The pairs of elements are stored in sorted order according to the first element of the pair (the map’s key). For example:
  >>> encode_map_int_float({})
  b’’
  >>> encode_map_int_float({1: 0,
  ...                       -1: 3.1415})
  b\xff\xff\xff\xff\xff\xff\xff\xffo\x12\x83\xc0\xca!\t@’ \
  b\x01\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00
map(float, string) format  Maps from floats to strings are formed by encoding the individual elements, where values are prefixed by an unsigned 4-byte little endian integer indicating their length. The pairs of elements are stored in sorted order according to the first element of the pair (the map’s key). For example:
  >>> encode_map_float_string({})
  b’’
  >>> encode_map_float_string({0: ’hello’,
  ...                          3.1415: ’world’})
  b\x00\x00\x00\x00\x00\x00\x00\x00\x05\x00\x00\x00hello’ \
  b’o\x12\x83\xc0\xca!\t@\x05\x00\x00\x00world’
map(float, int) format  Maps from floats to ints are formed by encoding the individual elements. The pairs of elements are stored in sorted order according to the first element of the pair (the map’s key). For example:
  >>> encode_map_float_int({})
  b’’
  >>> encode_map_float_int({0: 1,
  ...                       3.1415: -1})
  b\x00\x00\x00\x00\x00\x00\x00\x00\x01\x00\x00\x00\x00\x00\x00\x00 \
  b’o\x12\x83\xc0\xca!\t@\xff\xff\xff\xff\xff\xff\xff\xff
map(float, float) format  Maps from floats to floats are formed by encoding the individual elements. The pairs of elements are stored in sorted order according to the first element of the pair (the map’s key). For example:
  >>> encode_map_float_float({})
  b’’
  >>> encode_map_float_float({0: 1,
  ...                         3.1415: -1})
  b\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\xf0?’ \
  b’o\x12\x83\xc0\xca!\t@\x00\x00\x00\x00\x00\x00\xf0\xbf
12.1.6.3 Serialization API

The serialization API supports serialization of all datatypes supported by HyperDex. Of course, feel free to manually encode data structures, especially where doing so can make use of efficient stack-allocated data structures. struct hyperdex_ds_arena  The packing routines described below may occasionally have to allocate memory into which the encoded forms of the datatypes are copied. To free the programmer from the burden of having to manually allocate and free each of these pieces of memory, the data structures API allocates all memory via an instance of struct hyperdex_ds_arena. Via a single call to hyperdex_ds_arena_destroy, all memory allocated via the arena is free’d. struct hyperdex_ds_arena is intentionally defined as an incomplete type because its internals are subject to change. To create an arena, call hyperdex_ds_arena_create. The arena should subsequently be destroyed via hyperdex_ds_arena_destroy.

  struct hyperdex_ds_arena* hyperdex_ds_arena_create();
Create a new arena for alocating memory. On success, this function returns a non-null pointer for the new arena. On failure, the function returns NULL, indicating that memory allocation failed. It is the caller’s responsibility to pass this function to hyperdex_ds_arena_destroy when finished.
  void hyperdex_ds_arena_destroy(struct hyperdex_ds_arena* arena);

Free all memory associated with arena. This function always succeeds. serialize string  No serialization is necessary for string data types. For convenience, the serialization API provides a copy function that copies a string into arena-allocated memory.

  int hyperdex_ds_copy_string(struct hyperdex_ds_arena* arena, const char* str,
                              size_t str_sz, enum hyperdex_ds_returncode* status,
                              const char** value, size_t* value_sz);
Copy the string str/str_sz into memory allocated via arena and return the copy via value and value_sz. This function will fail and return -1 if there is insufficient memory available for copying the string. All pointers returned by this function remain valid until arena is destroyed. The client should not attempt to free the returned copy. serialize int 
  void hyperdex_ds_pack_int(int64_t num, char* value);
Packs num into the bytes pointed to by buf. This function always succeeds. It is the caller’s responsibility to ensure that buf points to at least 8 B.
  int hyperdex_ds_copy_int(struct hyperdex_ds_arena* arena, int64_t num,
                           enum hyperdex_ds_returncode* status,
                           const char** value, size_t* value_sz);

Encode num into memory allocated via arena and return the value via value and value_sz. This function will fail and return -1 if there is insufficient memory available for encoding the nubmer. All pointers returned by this function remain valid until arena is destroyed. The client should not attempt to free the returned copy. serialize float 

  void hyperdex_ds_pack_float(double num, char* value);
Pack num into the bytes pointed to by buf. This function always succeeds. It is the caller’s responsibility to ensure that buf points to at least 8 B.
  int hyperdex_ds_copy_float(struct hyperdex_ds_arena* arena, double num,
                             enum hyperdex_ds_returncode* status,
                             const char** value, size_t* value_sz);

Encode num into memory allocated via arena and return the value via value and value_sz. This function will fail and return -1 if there is insufficient memory available for encoding the nubmer. All pointers returned by this function remain valid until arena is destroyed. The client should not attempt to free the returned copy. serialize lists  The below functions incrementally build lists, performing all relevant error checking to ensure that the resuling HyperDex list is well-formed. The first element appended to the list implicitly determines the type of the list. All subsequent calls that push elements of a different type will fail.

  struct hyperdex_ds_list* hyperdex_ds_allocate_list(struct hyperdex_ds_arena* arena);
Create a new dynamic list. This function will fail and return NULL should memory allocation fail.
  int hyperdex_ds_list_insert_string(struct hyperdex_ds_list* list,
                                     const char* str, size_t str_sz,
                                     enum hyperdex_ds_returncode* status);

Append the string str/str_sz to list. This function will fail and return -1 if memory allocation fails, or the list is not a list of strings.

  int hyperdex_ds_list_insert_int(struct hyperdex_ds_list* list, int64_t num,
                                  enum hyperdex_ds_returncode* status);

Append the integer num to list. This function will fail and return -1 if memory allocation fails, or the list is not a list of integers.

  int hyperdex_ds_list_insert_float(struct hyperdex_ds_list* list, double num,
                                    enum hyperdex_ds_returncode* status);

Append the float num to list. This function will fail and return -1 if memory allocation fails or the list is not a list of floats.

  int hyperdex_ds_list_finalize(struct hyperdex_ds_list*,
                                enum hyperdex_ds_returncode* status,
                                const char** value, size_t* value_sz,
                                enum hyperdatatype* datatype);

Finalize the list by writing its elements into a bytestring. This function returns the bytestring and the list type. It will fail and return -1 if memory allocation fails. serialize sets  The below functions incrementally build sets, performing all relevant error checking to ensure that the resuling HyperDex set is well-formed. The first element inserted into the set implicitly determines the type of the set. All subsequent calls that insert elements of different types will fail.

  struct hyperdex_ds_set* hyperdex_ds_allocate_set(struct hyperdex_ds_arena* arena);
Create a new dynamic set. This function will fail and return NULL should memory allocation fail.
  int hyperdex_ds_set_insert_string(struct hyperdex_ds_set* set,
                                    const char* str, size_t str_sz,
                                    enum hyperdex_ds_returncode* status);

Insert the string str/str_sz into set. This function will fail and return -1 if memory allocation fails, or the set is not a set of strings.

  int hyperdex_ds_set_insert_int(struct hyperdex_ds_set* set, int64_t num,
                                 enum hyperdex_ds_returncode* status);

Insert the integer num into set. This function will fail and return -1 if memory allocation fails, or the set is not a set of integers.

  int hyperdex_ds_set_insert_float(struct hyperdex_ds_set* set, double num,
                                   enum hyperdex_ds_returncode* status);

Insert the float num into set. This function will fail and return -1 if memory allocation fails, or the set is not a set of floats.

  int hyperdex_ds_set_finalize(struct hyperdex_ds_set*,
                               enum hyperdex_ds_returncode* status,
                               const char** value, size_t* value_sz,
                               enum hyperdatatype* datatype);

Finalize the set by writing its elements into a bytestring. This function returns the bytestring and the set type. It will fail and return -1 if memory allocation fails. serialize maps  The below functions incrementally build maps, performing all relevant error checking to ensure that the resuling HyperDex map is well-formed. The first key/value-pair inserted into the map implicitly determines the type of the map. All subsequent calls that insert elements of different types will fail. The map is built by alternating calls to the key/value functions described below, starting with a key-based function. This keeps the number of cases linear in the number of primitive types a map may contain, rather than appending key-value pairs directly (which would require a quadratic number of calls).

  struct hyperdex_ds_map* hyperdex_ds_allocate_map(struct hyperdex_ds_arena* arena);
Create a new dynamic map. This function will fail and return NULL should memory allocation fail.
  int hyperdex_ds_map_insert_key_string(struct hyperdex_ds_map* map,
                                        const char* str, size_t str_sz,
                                        enum hyperdex_ds_returncode* status);

Set the key of the next pair to be inserted into map to the string specified by str and str_sz. This function will fail and return -1 if memory allocation fails, or the map does not use strings for keys.

  int hyperdex_ds_map_insert_val_string(struct hyperdex_ds_map* map,
                                        const char* str, size_t str_sz,
                                        enum hyperdex_ds_returncode* status);

Set the value of the next pair to be inserted into map to the string specified by str and str_sz, and insert the pair. This function will fail and return -1 if memory allocation fails, or the map does not use strings for values.

  int hyperdex_ds_map_insert_key_int(struct hyperdex_ds_map* map,
                                     int64_t num,
                                     enum hyperdex_ds_returncode* status);

Set the key of the next pair to be inserted into map to the integer specified by num. This function will fail and return -1 if memory allocation fails, or the map does not nuse integers for keys.

  int hyperdex_ds_map_insert_val_int(struct hyperdex_ds_map* map,
                                     int64_t num,
                                     enum hyperdex_ds_returncode* status);

Set the value of the next pair to be inserted into map to the integer specified by num, and insert the pair. This function will fail and return -1 if memory allocation fails, or the map does not use integers for values.

  int hyperdex_ds_map_insert_key_float(struct hyperdex_ds_map* map,
                                       double num,
                                       enum hyperdex_ds_returncode* status);

Set the key of the next pair to be inserted into map to the float specified by num. This function will fail and return -1 if memory allocation fails, or the map does not use floats for keys.

  int hyperdex_ds_map_insert_val_float(struct hyperdex_ds_map* map,
                                       double num,
                                       enum hyperdex_ds_returncode* status);

Set the value of the next pair to be inserted into map to the float specified by num. This function will fail and return -1 if memory allocation fails, or the map does not use floats for values.

  int hyperdex_ds_map_finalize(struct hyperdex_ds_map*,
                               enum hyperdex_ds_returncode* status,
                               const char** value, size_t* value_sz,
                               enum hyperdatatype* datatype);

Finalize the map by writing its key/value-pairs into a bytestring. This function returns the bytestring and the map type. It will fail and return -1 if memory allocation fails, or an uneven number of key/value calls were made.

12.1.6.4 Deserialization API

The deserialization API provides routines to unpack ints and floats, and iterate the elements in lists, sets, and maps. Iterators return elements one-by-one with a minimal amount of copying and allocation. All iterators are used in the same pattern. For example, to iterate a list of integers:

  /* C Includes */
  #include <stdio.h>
  #include <stdlib.h>
  
  /* HyperDex Includes */

  #include <hyperdex/datastructures.h>
  
  int
  main(int argc, const char* argv[])
  {
     int64_t num;

     const char* value = "\x01\x00\x00\x00\x00\x00\x00\x00"
                         "\xff\xff\xff\xff\xff\xff\xff\xff"

                         "\xef\xbe\xad\xde\x00\x00\x00\x00";
     size_t value_sz = 24;
     int status = 0;

     hyperdex_ds_iterator iter;
     hyperdex_ds_iterator_init(&iter, HYPERDATATYPE_LIST_INT64, value, value_sz);

  
     while ((status = hyperdex_ds_iterate_list_int_next(&iter, &num)) > 0)
     {
         printf("%ld\n", num);

     }
  
     if (status < 0)
     {
         printf("error: corrupt list\n");
     }
  
     return EXIT_SUCCESS;
  }

Compile and run this example with:

  $ cc -o iterate iterate.c pkg-config --cflags --libs hyperdex-client
  $ ./iterate
  1
  -1
  3735928559

The function hyperdex_ds_iterator_init sets up the iterator. Each container data type has a specialized iteration function. All iterators share the same initialization function.

  void hyperdex_ds_iterator_init(struct hyperdex_ds_iterator* iter,
                                 enum hyperdatatype datatype,
                                 const char* value,
                                 size_t value_sz);

Initialize an iterator for the given data type/value. This function always succeeds. deserialize string  No deserialization is necessary for string data types. deserialize int 

  int hyperdex_ds_unpack_int(const char* buf, size_t buf_sz, int64_t* num);
Unpack num from buf/buf_sz. This function will fail and return -1 if buf_sz is not exactly 8 B. deserialize float 
  int hyperdex_ds_unpack_float(const char* buf, size_t buf_sz, double* num);
Unpack num from buf/buf_sz. This function will fail and return -1 if buf_sz is not exactly 8 B. deserialize lists 
  int hyperdex_ds_iterate_list_string_next(struct hyperdex_ds_iterator* iter,
                                           const char** str, size_t* str_sz);
Return the next string element in the list. This function will return 1 if an element is returned, 0 if there are no elements to return, and -1 if the list of strings is malformed. The falue stored in *str is a pointer into the list of strings and should not be free’d by the application.
  int hyperdex_ds_iterate_list_int_next(struct hyperdex_ds_iterator* iter, int64_t* num);

Return the next integer element in the list. This function will return 1 if an element is returned, 0 if there are no elements to return, and -1 if the list of integers is malformed.

  int hyperdex_ds_iterate_list_float_next(struct hyperdex_ds_iterator* iter, double* num);

Return the next float element in the list. This function will return 1 if an element is returned, 0 if there are no elements to return, and -1 if the list of floats is malformed. deserialize sets 

  int hyperdex_ds_iterate_set_string_next(struct hyperdex_ds_iterator* iter,
                                          const char** str, size_t* str_sz);
Return the next string element in the set. This function will return 1 if an element is returned, 0 if there are no elements to return, and -1 if the set of strings is malformed. The value stored in *str is a pointer into the set of strings and should not be free’d by the application.
  int hyperdex_ds_iterate_set_int_next(struct hyperdex_ds_iterator* iter, int64_t* num);

Return the next integer element in the set. This function will return 1 if an element is returned, 0 if there are no elements to return, and -1 if the set of ints is malformed.

  int hyperdex_ds_iterate_set_float_next(struct hyperdex_ds_iterator* iter, double* num);

Return the next float element in the set. This function will return 1 if an element is returned, 0 if there are no elements to return, and -1 if the set of ints is malformed. deserialize maps 

  int hyperdex_ds_iterate_map_string_string_next(struct hyperdex_ds_iterator* iter,
                                                 const char** key, size_t* key_sz,
                                                 const char** val, size_t* val_sz);
Return the next pair of (string, string) in the map. This function will return 1 if an element is returned, 0 if there are no elements to return, and -1 if the map is malformed. The values stored in *key and *val are pointers into the map and should not be free’d by the application.
  int hyperdex_ds_iterate_map_string_int_next(struct hyperdex_ds_iterator* iter,
                                              const char** key, size_t* key_sz,
                                              int64_t* val);

Return the next pair of (string, int) in the map. This function will return 1 if an element is returned, 0 if there are no elements to return, and -1 if the map is malformed. The value stored in *key is a pointer into the map and should not be free’d by the application.

  int hyperdex_ds_iterate_map_string_float_next(struct hyperdex_ds_iterator* iter,
                                                const char** key, size_t* key_sz,
                                                double* val);

Return the next pair of (string, float) in the map. This function will return 1 if an element is returned, 0 if there are no elements to return, and -1 if the map is malformed. The value stored in *key is a pointer into the map and should not be free’d by the application.

  int hyperdex_ds_iterate_map_int_string_next(struct hyperdex_ds_iterator* iter,
                                              int64_t* key,
                                              const char** val, size_t* val_sz);

Return the next pair of (int, string) in the map. This function will return 1 if an element is returned, 0 if there are no elements to return, and -1 if the map is malformed. The value stored in *val is a pointer into the map and should not be free’d by the application.

  int hyperdex_ds_iterate_map_int_int_next(struct hyperdex_ds_iterator* iter,
                                           int64_t* key, int64_t* val);

Return the next pair of (int, int) in the map. This function will return 1 if an element is returned, 0 if there are no elements to return, and -1 if the map is malformed.

  int hyperdex_ds_iterate_map_int_float_next(struct hyperdex_ds_iterator* iter,
                                             int64_t* key, double* val);

Return the next pair of (int, float) in the map. This function will return 1 if an element is returned, 0 if there are no elements to return, and -1 if the map is malformed.

  int hyperdex_ds_iterate_map_float_string_next(struct hyperdex_ds_iterator* iter,
                                                double* key,
                                                const char** val, size_t* val_sz);

Return the next pair of (float, string) in the map. This function will return 1 if an element is returned, 0 if there are no elements to return, and -1 if the map is malformed. The value stored in *val is a pointer into the map and should not be free’d by the application.

  int hyperdex_ds_iterate_map_float_int_next(struct hyperdex_ds_iterator* iter,
                                             double* key, int64_t* val);

Return the next pair of (float, int) in the map. This function will return 1 if an element is returned, 0 if there are no elements to return, and -1 if the map is malformed.

  int hyperdex_ds_iterate_map_float_float_next(struct hyperdex_ds_iterator* iter,
                                               double* key, double* val);

Return the next pair of (float, float) in the map. This function will return 1 if an element is returned, 0 if there are no elements to return, and -1 if the map is malformed.

12.1.6.5 Memory Management Utilties

The data structures API provides utility functions for allocating structures from the arena, obviating the need to free them individually.

  struct hyperdex_client_attribute*
  hyperdex_ds_allocate_attribute(struct hyperdex_ds_arena* arena, size_t sz);

Allocate an array of struct hyperdex_client_attribute. On success, this function returns a non-null pointer containing sz elements. On failure, the function returns NULL, indicating that memory allocation failed. The memory will remain valid until the arena is destroyed and should not be free’d independently by the application.

  struct hyperdex_client_attribute_check*
  hyperdex_ds_allocate_attribute_check(struct hyperdex_ds_arena* arena, size_t sz);

Allocate an array of struct hyperdex_client_attribute_check. On success, this function returns a non-null pointer containing sz elements. On failure, the function returns NULL, indicating that memory allocation failed. The memory will remain valid until the arena is destroyed and should not be free’d independently by the application.

  struct hyperdex_client_map_attribute*
  hyperdex_ds_allocate_map_attribute(struct hyperdex_ds_arena* arena, size_t sz);

Allocate an array of struct hyperdex_client_map_attribute. On success, this function returns a non-null pointer containing sz elements. On failure, the function returns NULL, indicating that memory allocation failed. The memory will remain valid until the arena is destroyed and should not be free’d independently by the application.

12.1.7 Attributes

In HyperDex, attributes specified named values that comprise an object. For instance, in Chapter Quick Start, the phonebook space has attributes “username”, “first”, “last”, and “phone”. The C API represents such attributes using struct hyperdex_client_attribute. The C definition of this struct is:

  struct hyperdex_client_attribute
  {
      const char* attr; /* NULL-terminated */
      const char* value;
      size_t value_sz;
      enum hyperdatatype datatype;
  };

This struct specifies the name, value, and data type of the attribute. The attr field is a NULL-terminated C-string that names the attribute affected by the value. The value and value_sz fields contain a properly formatted byte string and its size. The datatype field indicates the encoding of the byte string.

The interpretation of an attribute is dependent upon the operation being performed. In the case of hyperdex_client_put, the attributes directly convey the values to be stored; hyperdex_client_get returns the stored attributes. Other operations, such as hyperdex_client_string_prepend interpret the attribute as an argument to the operation. In the case of prepend, the attribute specifies the value to be prepended.

12.1.8 Map Attributes

Some HyperDex operations affect key-value pairs contained within maps. These operations use struct hyperdex_client_map_attribute to specify the name of the attribute affected, the key within the map, and the value associated with that key. The C definition of this struct is:

  struct hyperdex_client_map_attribute
  {
      const char* attr; /* NULL-terminated */
      const char* map_key;
      size_t map_key_sz;
      enum hyperdatatype map_key_datatype;
      const char* value;
      size_t value_sz;
      enum hyperdatatype value_datatype;
  };

The struct specifies the name, key, and value of to be used for the operation. The map_key_* and value_* fields specify, respectively, the key and value of the element within the map. The relative fields are specified as byte strings with associated data types. The attr field specifies the name of the map.

12.1.9 Predicates

In HyperDex, a predicate is an expression about an attribute that is true or false. Predicates are specified to HyperDex using struct hyperdex_client_attribute_check which is defined as:

  struct hyperdex_client_attribute_check
  {
      const char* attr; /* NULL-terminated */
      const char* value;
      size_t value_sz;
      enum hyperdatatype datatype;
      enum hyperpredicate predicate;
  };

Note that this struct closely resembes struct hyperdex_client_attribute, with the addition of a field named predicate. This field is an enum with the following values:

HYPERPREDICATE_FAIL
Always fail.
HYPERPREDICATE_EQUALS
Check that the existing value is equal to the one specified by value/value_sz.
HYPERPREDICATE_LESS_EQUAL
Check that the existing value is less than or equal to the one specified by value/value_sz.
HYPERPREDICATE_GREATER_EQUAL
Check that the existing value is greater than or equal to the one specified by value/value_sz.
HYPERPREDICATE_REGEX
Check that the existing value matches the regular expression stored in as a string in value/value_sz.
HYPERPREDICATE_LENGTH_EQUALS
Check that the existing container or string has a length equal to the integer stored in value/value_sz.
HYPERPREDICATE_LENGTH_LESS_EQUAL
Check that the existing container or string has a length less than or equal to the integer stored in value/value_sz.
HYPERPREDICATE_LENGTH_GREATER_EQUAL
Check that the existing container or string has a length greater than or equal to the integer stored in value/value_sz.
HYPERPREDICATE_CONTAINS
Check that the container contains an element matching value/value_sz.

12.1.10 Error Handling

Every call in the client provides a means for reporting failure. After each call, your application should for the error and react appropriately. Depending upon the error, your application may retry the request, or may need to take more drastic action.

Errors are typically reported via enum hyperdex_client_returncode defined in hyperdex/client.h. Values for this enum fall into three categories: values returned during normal operation, values returned to indicate anticipated errors, and values that should never be returned in practice.

The common-case returncodes are:

HYPERDEX_CLIENT_SUCCESS
The operation was successful and no errors occurred.
HYPERDEX_CLIENT_NOTFOUND
The operation finished because the requested object was not found.
HYPERDEX_CLIENT_SEARCHDONE
An operation that potentially returns multiple objects. For instance, a search has finished and will no longer be returned via loop.
HYPERDEX_CLIENT_CMPFAIL
The predicate specified as part of a conditional operation was not true.
HYPERDEX_CLIENT_READONLY
The cluster is in read-only mode and not accepting write operations.

The following errors stem from environmental problems or problems with the application’s usage of HyperDex. These errors are generally easy to remedy and are anticipated by the client library.

HYPERDEX_CLIENT_UNKNOWNSPACE
The specified space does not exist. Ensure that a space exists before trying to manipulate its data.
HYPERDEX_CLIENT_COORDFAIL
The connection to the coordinator has failed. The application should back off before retrying.

Note that the connection to the coordinator is not a simple TCP connection, and is redundant if the coordinator consists of multiple servers. This error indicates to the application that the redundancy has failed and that the application should back-off.

HYPERDEX_CLIENT_SERVERERROR
A server returned a nonsensical result to the client library. Generally retrying the request should be sufficient to overcome the problem.
HYPERDEX_CLIENT_POLLFAILED
The poll system call failed in an unexpected manner. Typically, this means that the application using the HyperDex library has mismanaged its file descriptors and improperly altered descriptors in use by the HyperDex library.

This generally indicates that there is a bug in the HyperDex client library, the application using the library, or both.

HYPERDEX_CLIENT_OVERFLOW
An integer operation failed to complete because it would have resulted in signed overflow.
HYPERDEX_CLIENT_RECONFIGURE
The server responsible for managing the operation failed while the operation was in-flight.
HYPERDEX_CLIENT_TIMEOUT
The hyperdex_client_loop operation exceeded its timeout without completing an outstanding operation. This does not affect the status of any outstanding operation.
HYPERDEX_CLIENT_UNKNOWNATTR
The operation references an attribute that is not part of the space. Make sure to use attributes within the space’s schema.
HYPERDEX_CLIENT_DUPEATTR
The operation references an attribute multiple times in a way that is not permitted.
HYPERDEX_CLIENT_NONEPENDING
The hyperdex_client_loop call was made, but no operations were outstanding. This generally indicates that the loop call was called too many times for the operations issued.
HYPERDEX_CLIENT_DONTUSEKEY
The operation attempted to mutate the key, which is not permitted.
HYPERDEX_CLIENT_WRONGTYPE
The attribute or predicate was not compatible with the type in the space’s schema. For example, the operation may have attempted to issue a PUT operation that writes an integer to a non-integer datatype, or tries to perform string operations on a non-string data type. Check that the operation performed is compatible with the data type of the affected attributes.
HYPERDEX_CLIENT_NOMEM
The library failed to allocate memory.
HYPERDEX_CLIENT_INTERRUPTED
The HyperDex library was interrupted by a signal. Read more about signals in Section 12.1.12.
HYPERDEX_CLIENT_CLUSTER_JUMP
The client library started receiving configurations for a different HyperDex cluster. This can happen if a new coordinator is restarted on the same address that the client connects to. This error will not be persistent. The client library will switch to the new cluster configuration, and this error just serves as a notification to the application.
HYPERDEX_CLIENT_OFFLINE
All servers responsible for handling the specified operation are currently offline and unavailable, whether due to failure or planned downtime.

The following errors indicate significant bugs within the client or application. In practice they should never happen and indicate bugs within HyperDex itself. They are used as one would use an assert statement to enforce an invariant.

HYPERDEX_CLIENT_INTERNAL
One or more of the HyperDex client library’s internal invariants have been broken. It’s best to destroy and recreate the client.
HYPERDEX_CLIENT_EXCEPTION
The C library is implemented internally using C++. C++ generated an unhandled exception that was caught at the C boundary. This indicates a bug in HyperDex, and exists only as a safeguard. Applications should never see this error.
HYPERDEX_CLIENT_GARBAGE
This value is reserved as a well-defined value that the library will never return, and that is not used as a constant anywhere else within HyperDex.

Note that an asynchronous application should distinguish between local errors which affect one outstanding operation, and global errors that transiently affect all operations, but do not change the completion status of those operations.

Local errors are always returned via the enum hyperdex_client_returncode* pointer passed at the time the application initated the operation. These errors may either result from the application returning a negative operation id, in which case the operation immediately completes, or from the result of a successful hyperdex_client_loop call. In either case, the error has no impact on the result of any other operation.

Global errors are always returned via the enum hyperdex_client_returncode* pointer passed to the most recent invocation of hyperdex_client_loop. These errors are not localized to any particular operation and indicate errors that are non-permanent. Example global errors include application-requested timeouts, interruptions by signals, and temporary non-connectivity with the coordinator.

12.1.11 Operations

12.1.11.1 get

Get an object by key.

Behavior:  Definition: 
  int64_t hyperdex_client_get(struct hyperdex_client* client,
          const char* space,
          const char* key, size_t key_sz,
          enum hyperdex_client_returncode* status,
          const struct hyperdex_client_attribute** attrs, size_t* attrs_sz);
Parameters:  Returns: 
12.1.11.2 get_partial

Get part of an object by key. This will return only the listed attribute names.

Behavior:  Definition: 
  int64_t hyperdex_client_get_partial(struct hyperdex_client* client,
          const char* space,
          const char* key, size_t key_sz,
          const char** attrnames, size_t attrnames_sz,
          enum hyperdex_client_returncode* status,
          const struct hyperdex_client_attribute** attrs, size_t* attrs_sz);
Parameters:  Returns: 
12.1.11.3 put

Store or update an object by key. Existing values will be overwritten with the values specified by attrs. Values not specified by attrs will be preserved.

Behavior:  Definition: 
  int64_t hyperdex_client_put(struct hyperdex_client* client,
          const char* space,
          const char* key, size_t key_sz,
          const struct hyperdex_client_attribute* attrs, size_t attrs_sz,
          enum hyperdex_client_returncode* status);
Parameters:  Returns: 
12.1.11.4 cond_put

Conditionally store or update an object by key. Existing values will be overwritten with the values specified by attrs. Values not specified by attrs will be preserved.

Behavior:  Definition: 
  int64_t hyperdex_client_cond_put(struct hyperdex_client* client,
          const char* space,
          const char* key, size_t key_sz,
          const struct hyperdex_client_attribute_check* checks, size_t checks_sz,
          const struct hyperdex_client_attribute* attrs, size_t attrs_sz,
          enum hyperdex_client_returncode* status);
Parameters:  Returns: 
12.1.11.5 put_if_not_exist

Store a new object by key. Values not specified by attrs will be initialized to their defaults.

Behavior:  Definition: 
  int64_t hyperdex_client_put_if_not_exist(struct hyperdex_client* client,
          const char* space,
          const char* key, size_t key_sz,
          const struct hyperdex_client_attribute* attrs, size_t attrs_sz,
          enum hyperdex_client_returncode* status);
Parameters:  Returns: 
12.1.11.6 del

Delete an object by key.

Behavior:  Definition: 
  int64_t hyperdex_client_del(struct hyperdex_client* client,
          const char* space,
          const char* key, size_t key_sz,
          enum hyperdex_client_returncode* status);
Parameters:  Returns: 
12.1.11.7 cond_del

Conditionally delete an object by key.

Behavior:  Definition: 
  int64_t hyperdex_client_cond_del(struct hyperdex_client* client,
          const char* space,
          const char* key, size_t key_sz,
          const struct hyperdex_client_attribute_check* checks, size_t checks_sz,
          enum hyperdex_client_returncode* status);
Parameters:  Returns: 
12.1.11.8 atomic_add

Add the specified number to the existing value for each attribute.

Behavior:  Definition: 
  int64_t hyperdex_client_atomic_add(struct hyperdex_client* client,
          const char* space,
          const char* key, size_t key_sz,
          const struct hyperdex_client_attribute* attrs, size_t attrs_sz,
          enum hyperdex_client_returncode* status);
Parameters:  Returns: 
12.1.11.9 cond_atomic_add

Conditionally add the specified number to the existing value for each attribute.

Behavior:  Definition: 
  int64_t hyperdex_client_cond_atomic_add(struct hyperdex_client* client,
          const char* space,
          const char* key, size_t key_sz,
          const struct hyperdex_client_attribute_check* checks, size_t checks_sz,
          const struct hyperdex_client_attribute* attrs, size_t attrs_sz,
          enum hyperdex_client_returncode* status);
Parameters:  Returns: 
12.1.11.10 atomic_sub

Subtract the specified number from the existing value for each attribute.

Behavior:  Definition: 
  int64_t hyperdex_client_atomic_sub(struct hyperdex_client* client,
          const char* space,
          const char* key, size_t key_sz,
          const struct hyperdex_client_attribute* attrs, size_t attrs_sz,
          enum hyperdex_client_returncode* status);
Parameters:  Returns: 
12.1.11.11 cond_atomic_sub

Conditionally subtract the specified number from the existing value for each attribute.

Behavior:  Definition: 
  int64_t hyperdex_client_cond_atomic_sub(struct hyperdex_client* client,
          const char* space,
          const char* key, size_t key_sz,
          const struct hyperdex_client_attribute_check* checks, size_t checks_sz,
          const struct hyperdex_client_attribute* attrs, size_t attrs_sz,
          enum hyperdex_client_returncode* status);
Parameters:  Returns: 
12.1.11.12 atomic_mul

Multiply the existing value by the specified number for each attribute.

Behavior:  Definition: 
  int64_t hyperdex_client_atomic_mul(struct hyperdex_client* client,
          const char* space,
          const char* key, size_t key_sz,
          const struct hyperdex_client_attribute* attrs, size_t attrs_sz,
          enum hyperdex_client_returncode* status);
Parameters:  Returns: 
12.1.11.13 cond_atomic_mul

Conditionally multiply the existing value by the specified number for each attribute.

Behavior:  Definition: 
  int64_t hyperdex_client_cond_atomic_mul(struct hyperdex_client* client,
          const char* space,
          const char* key, size_t key_sz,
          const struct hyperdex_client_attribute_check* checks, size_t checks_sz,
          const struct hyperdex_client_attribute* attrs, size_t attrs_sz,
          enum hyperdex_client_returncode* status);
Parameters:  Returns: 
12.1.11.14 atomic_div

Divide the existing value by the specified number for each attribute.

Behavior:  Definition: 
  int64_t hyperdex_client_atomic_div(struct hyperdex_client* client,
          const char* space,
          const char* key, size_t key_sz,
          const struct hyperdex_client_attribute* attrs, size_t attrs_sz,
          enum hyperdex_client_returncode* status);
Parameters:  Returns: 
12.1.11.15 cond_atomic_div

Conditionally divide the existing value by the specified number for each attribute.

Behavior:  Definition: 
  int64_t hyperdex_client_cond_atomic_div(struct hyperdex_client* client,
          const char* space,
          const char* key, size_t key_sz,
          const struct hyperdex_client_attribute_check* checks, size_t checks_sz,
          const struct hyperdex_client_attribute* attrs, size_t attrs_sz,
          enum hyperdex_client_returncode* status);
Parameters:  Returns: 
12.1.11.16 atomic_mod

Store the existing value modulo the specified number for each attribute.

Behavior:  Definition: 
  int64_t hyperdex_client_atomic_mod(struct hyperdex_client* client,
          const char* space,
          const char* key, size_t key_sz,
          const struct hyperdex_client_attribute* attrs, size_t attrs_sz,
          enum hyperdex_client_returncode* status);
Parameters:  Returns: 
12.1.11.17 cond_atomic_mod

Conditionally store the existing value modulo the specified number for each attribute.

Behavior:  Definition: 
  int64_t hyperdex_client_cond_atomic_mod(struct hyperdex_client* client,
          const char* space,
          const char* key, size_t key_sz,
          const struct hyperdex_client_attribute_check* checks, size_t checks_sz,
          const struct hyperdex_client_attribute* attrs, size_t attrs_sz,
          enum hyperdex_client_returncode* status);
Parameters:  Returns: 
12.1.11.18 atomic_and

Store the bitwise AND of the existing value and the specified number for each attribute.

Behavior:  Definition: 
  int64_t hyperdex_client_atomic_and(struct hyperdex_client* client,
          const char* space,
          const char* key, size_t key_sz,
          const struct hyperdex_client_attribute* attrs, size_t attrs_sz,
          enum hyperdex_client_returncode* status);
Parameters:  Returns: 
12.1.11.19 cond_atomic_and

Conditionally store the bitwise AND of the existing value and the specified number for each attribute.

Behavior:  Definition: 
  int64_t hyperdex_client_cond_atomic_and(struct hyperdex_client* client,
          const char* space,
          const char* key, size_t key_sz,
          const struct hyperdex_client_attribute_check* checks, size_t checks_sz,
          const struct hyperdex_client_attribute* attrs, size_t attrs_sz,
          enum hyperdex_client_returncode* status);
Parameters:  Returns: 
12.1.11.20 atomic_or

Store the bitwise OR of the existing value and the specified number for each attribute.

Behavior:  Definition: 
  int64_t hyperdex_client_atomic_or(struct hyperdex_client* client,
          const char* space,
          const char* key, size_t key_sz,
          const struct hyperdex_client_attribute* attrs, size_t attrs_sz,
          enum hyperdex_client_returncode* status);
Parameters:  Returns: 
12.1.11.21 cond_atomic_or

Conditionally store the bitwise OR of the existing value and the specified number for each attribute.

Behavior:  Definition: 
  int64_t hyperdex_client_cond_atomic_or(struct hyperdex_client* client,
          const char* space,
          const char* key, size_t key_sz,
          const struct hyperdex_client_attribute_check* checks, size_t checks_sz,
          const struct hyperdex_client_attribute* attrs, size_t attrs_sz,
          enum hyperdex_client_returncode* status);
Parameters:  Returns: 
12.1.11.22 atomic_xor

Store the bitwise XOR of the existing value and the specified number for each attribute.

Behavior:  Definition: 
  int64_t hyperdex_client_atomic_xor(struct hyperdex_client* client,
          const char* space,
          const char* key, size_t key_sz,
          const struct hyperdex_client_attribute* attrs, size_t attrs_sz,
          enum hyperdex_client_returncode* status);
Parameters:  Returns: 
12.1.11.23 cond_atomic_xor

Conditionally store the bitwise XOR of the existing value and the specified number for each attribute.

Behavior:  Definition: 
  int64_t hyperdex_client_cond_atomic_xor(struct hyperdex_client* client,
          const char* space,
          const char* key, size_t key_sz,
          const struct hyperdex_client_attribute_check* checks, size_t checks_sz,
          const struct hyperdex_client_attribute* attrs, size_t attrs_sz,
          enum hyperdex_client_returncode* status);
Parameters:  Returns: 
12.1.11.24 string_prepend

Prepend the specified string to the existing value for each attribute.

Behavior:  Definition: 
  int64_t hyperdex_client_string_prepend(struct hyperdex_client* client,
          const char* space,
          const char* key, size_t key_sz,
          const struct hyperdex_client_attribute* attrs, size_t attrs_sz,
          enum hyperdex_client_returncode* status);
Parameters:  Returns: 
12.1.11.25 cond_string_prepend

Conditionally prepend the specified string to the existing value for each attribute.

Behavior:  Definition: 
  int64_t hyperdex_client_cond_string_prepend(struct hyperdex_client* client,
          const char* space,
          const char* key, size_t key_sz,
          const struct hyperdex_client_attribute_check* checks, size_t checks_sz,
          const struct hyperdex_client_attribute* attrs, size_t attrs_sz,
          enum hyperdex_client_returncode* status);
Parameters:  Returns: 
12.1.11.26 string_append

Append the specified string to the existing value for each attribute.

Behavior:  Definition: 
  int64_t hyperdex_client_string_append(struct hyperdex_client* client,
          const char* space,
          const char* key, size_t key_sz,
          const struct hyperdex_client_attribute* attrs, size_t attrs_sz,
          enum hyperdex_client_returncode* status);
Parameters:  Returns: 
12.1.11.27 cond_string_append

Conditionally append the specified string to the existing value for each attribute.

Behavior:  Definition: 
  int64_t hyperdex_client_cond_string_append(struct hyperdex_client* client,
          const char* space,
          const char* key, size_t key_sz,
          const struct hyperdex_client_attribute_check* checks, size_t checks_sz,
          const struct hyperdex_client_attribute* attrs, size_t attrs_sz,
          enum hyperdex_client_returncode* status);
Parameters:  Returns: 
12.1.11.28 list_lpush

Push the specified value onto the front of the list for each attribute.

Behavior:  Definition: 
  int64_t hyperdex_client_list_lpush(struct hyperdex_client* client,
          const char* space,
          const char* key, size_t key_sz,
          const struct hyperdex_client_attribute* attrs, size_t attrs_sz,
          enum hyperdex_client_returncode* status);
Parameters:  Returns: 
12.1.11.29 cond_list_lpush

Condtitionally push the specified value onto the front of the list for each attribute.

Behavior:  Definition: 
  int64_t hyperdex_client_cond_list_lpush(struct hyperdex_client* client,
          const char* space,
          const char* key, size_t key_sz,
          const struct hyperdex_client_attribute_check* checks, size_t checks_sz,
          const struct hyperdex_client_attribute* attrs, size_t attrs_sz,
          enum hyperdex_client_returncode* status);
Parameters:  Returns: 
12.1.11.30 list_rpush

Push the specified value onto the back of the list for each attribute.

Behavior:  Definition: 
  int64_t hyperdex_client_list_rpush(struct hyperdex_client* client,
          const char* space,
          const char* key, size_t key_sz,
          const struct hyperdex_client_attribute* attrs, size_t attrs_sz,
          enum hyperdex_client_returncode* status);
Parameters:  Returns: 
12.1.11.31 cond_list_rpush

Conditionally push the specified value onto the back of the list for each attribute.

Behavior:  Definition: 
  int64_t hyperdex_client_cond_list_rpush(struct hyperdex_client* client,
          const char* space,
          const char* key, size_t key_sz,
          const struct hyperdex_client_attribute_check* checks, size_t checks_sz,
          const struct hyperdex_client_attribute* attrs, size_t attrs_sz,
          enum hyperdex_client_returncode* status);
Parameters:  Returns: 
12.1.11.32 set_add

Add the specified value to the set for each attribute.

Behavior:  Definition: 
  int64_t hyperdex_client_set_add(struct hyperdex_client* client,
          const char* space,
          const char* key, size_t key_sz,
          const struct hyperdex_client_attribute* attrs, size_t attrs_sz,
          enum hyperdex_client_returncode* status);
Parameters:  Returns: 
12.1.11.33 cond_set_add

Conditionally add the specified value to the set for each attribute.

Behavior:  Definition: 
  int64_t hyperdex_client_cond_set_add(struct hyperdex_client* client,
          const char* space,
          const char* key, size_t key_sz,
          const struct hyperdex_client_attribute_check* checks, size_t checks_sz,
          const struct hyperdex_client_attribute* attrs, size_t attrs_sz,
          enum hyperdex_client_returncode* status);
Parameters:  Returns: 
12.1.11.34 set_remove

Remove the specified value from the set. If the value is not contained within the set, this operation will do nothing.

Behavior:  Definition: 
  int64_t hyperdex_client_set_remove(struct hyperdex_client* client,
          const char* space,
          const char* key, size_t key_sz,
          const struct hyperdex_client_attribute* attrs, size_t attrs_sz,
          enum hyperdex_client_returncode* status);
Parameters:  Returns: 
12.1.11.35 cond_set_remove

Conditionally remove the specified value from the set. If the value is not contained within the set, this operation will do nothing.

Behavior:  Definition: 
  int64_t hyperdex_client_cond_set_remove(struct hyperdex_client* client,
          const char* space,
          const char* key, size_t key_sz,
          const struct hyperdex_client_attribute_check* checks, size_t checks_sz,
          const struct hyperdex_client_attribute* attrs, size_t attrs_sz,
          enum hyperdex_client_returncode* status);
Parameters:  Returns: 
12.1.11.36 set_intersect

Store the intersection of the specified set and the existing value for each attribute.

Behavior:  Definition: 
  int64_t hyperdex_client_set_intersect(struct hyperdex_client* client,
          const char* space,
          const char* key, size_t key_sz,
          const struct hyperdex_client_attribute* attrs, size_t attrs_sz,
          enum hyperdex_client_returncode* status);
Parameters:  Returns: 
12.1.11.37 cond_set_intersect

Conditionally store the intersection of the specified set and the existing value for each attribute.

Behavior:  Definition: 
  int64_t hyperdex_client_cond_set_intersect(struct hyperdex_client* client,
          const char* space,
          const char* key, size_t key_sz,
          const struct hyperdex_client_attribute_check* checks, size_t checks_sz,
          const struct hyperdex_client_attribute* attrs, size_t attrs_sz,
          enum hyperdex_client_returncode* status);
Parameters:  Returns: 
12.1.11.38 set_union

Store the union of the specified set and the existing value for each attribute.

Behavior:  Definition: 
  int64_t hyperdex_client_set_union(struct hyperdex_client* client,
          const char* space,
          const char* key, size_t key_sz,
          const struct hyperdex_client_attribute* attrs, size_t attrs_sz,
          enum hyperdex_client_returncode* status);
Parameters:  Returns: 
12.1.11.39 cond_set_union

Conditionally store the union of the specified set and the existing value for each attribute.

Behavior:  Definition: 
  int64_t hyperdex_client_cond_set_union(struct hyperdex_client* client,
          const char* space,
          const char* key, size_t key_sz,
          const struct hyperdex_client_attribute_check* checks, size_t checks_sz,
          const struct hyperdex_client_attribute* attrs, size_t attrs_sz,
          enum hyperdex_client_returncode* status);
Parameters:  Returns: 
12.1.11.40 map_add

Insert a key-value pair into the map specified by each map-attribute.

Behavior:  Definition: 
  int64_t hyperdex_client_map_add(struct hyperdex_client* client,
          const char* space,
          const char* key, size_t key_sz,
          const struct hyperdex_client_map_attribute* mapattrs, size_t mapattrs_sz,
          enum hyperdex_client_returncode* status);
Parameters:  Returns: 
12.1.11.41 cond_map_add

Conditionally insert a key-value pair into the map specified by each map-attribute.

Behavior:  Definition: 
  int64_t hyperdex_client_cond_map_add(struct hyperdex_client* client,
          const char* space,
          const char* key, size_t key_sz,
          const struct hyperdex_client_attribute_check* checks, size_t checks_sz,
          const struct hyperdex_client_map_attribute* mapattrs, size_t mapattrs_sz,
          enum hyperdex_client_returncode* status);
Parameters:  Returns: 
12.1.11.42 map_remove

Remove a key-value pair from the map specified by each attribute. If there is no pair with the specified key within the map, this operation will do nothing.

Behavior:  Definition: 
  int64_t hyperdex_client_map_remove(struct hyperdex_client* client,
          const char* space,
          const char* key, size_t key_sz,
          const struct hyperdex_client_attribute* attrs, size_t attrs_sz,
          enum hyperdex_client_returncode* status);
Parameters:  Returns: 
12.1.11.43 cond_map_remove

Conditionally remove a key-value pair from the map specified by each attribute.

Behavior:  Definition: 
  int64_t hyperdex_client_cond_map_remove(struct hyperdex_client* client,
          const char* space,
          const char* key, size_t key_sz,
          const struct hyperdex_client_attribute_check* checks, size_t checks_sz,
          const struct hyperdex_client_attribute* attrs, size_t attrs_sz,
          enum hyperdex_client_returncode* status);
Parameters:  Returns: 
12.1.11.44 map_atomic_add

Add the specified number to the value of a key-value pair within each map.

Behavior:  Definition: 
  int64_t hyperdex_client_map_atomic_add(struct hyperdex_client* client,
          const char* space,
          const char* key, size_t key_sz,
          const struct hyperdex_client_map_attribute* mapattrs, size_t mapattrs_sz,
          enum hyperdex_client_returncode* status);
Parameters:  Returns: 
12.1.11.45 cond_map_atomic_add

Conditionally add the specified number to the value of a key-value pair within each map.

Behavior:  Definition: 
  int64_t hyperdex_client_cond_map_atomic_add(struct hyperdex_client* client,
          const char* space,
          const char* key, size_t key_sz,
          const struct hyperdex_client_attribute_check* checks, size_t checks_sz,
          const struct hyperdex_client_map_attribute* mapattrs, size_t mapattrs_sz,
          enum hyperdex_client_returncode* status);
Parameters:  Returns: 
12.1.11.46 map_atomic_sub

Subtract the specified number from the value of a key-value pair within each map.

Behavior:  Definition: 
  int64_t hyperdex_client_map_atomic_sub(struct hyperdex_client* client,
          const char* space,
          const char* key, size_t key_sz,
          const struct hyperdex_client_map_attribute* mapattrs, size_t mapattrs_sz,
          enum hyperdex_client_returncode* status);
Parameters:  Returns: 
12.1.11.47 cond_map_atomic_sub

Subtract the specified number from the value of a key-value pair within each map.

Behavior:  Definition: 
  int64_t hyperdex_client_cond_map_atomic_sub(struct hyperdex_client* client,
          const char* space,
          const char* key, size_t key_sz,
          const struct hyperdex_client_attribute_check* checks, size_t checks_sz,
          const struct hyperdex_client_map_attribute* mapattrs, size_t mapattrs_sz,
          enum hyperdex_client_returncode* status);
Parameters:  Returns: 
12.1.11.48 map_atomic_mul

Multiply the value of each key-value pair by the specified number for each map.

Behavior:  Definition: 
  int64_t hyperdex_client_map_atomic_mul(struct hyperdex_client* client,
          const char* space,
          const char* key, size_t key_sz,
          const struct hyperdex_client_map_attribute* mapattrs, size_t mapattrs_sz,
          enum hyperdex_client_returncode* status);
Parameters:  Returns: 
12.1.11.49 cond_map_atomic_mul

Conditionally multiply the value of each key-value pair by the specified number for each map.

Behavior:  Definition: 
  int64_t hyperdex_client_cond_map_atomic_mul(struct hyperdex_client* client,
          const char* space,
          const char* key, size_t key_sz,
          const struct hyperdex_client_attribute_check* checks, size_t checks_sz,
          const struct hyperdex_client_map_attribute* mapattrs, size_t mapattrs_sz,
          enum hyperdex_client_returncode* status);
Parameters:  Returns: 
12.1.11.50 map_atomic_div

Divide the value of each key-value pair by the specified number for each map.

Behavior:  Definition: 
  int64_t hyperdex_client_map_atomic_div(struct hyperdex_client* client,
          const char* space,
          const char* key, size_t key_sz,
          const struct hyperdex_client_map_attribute* mapattrs, size_t mapattrs_sz,
          enum hyperdex_client_returncode* status);
Parameters:  Returns: 
12.1.11.51 cond_map_atomic_div

Conditionally divide the value of each key-value pair by the specified number for each map.

Behavior:  Definition: 
  int64_t hyperdex_client_cond_map_atomic_div(struct hyperdex_client* client,
          const char* space,
          const char* key, size_t key_sz,
          const struct hyperdex_client_attribute_check* checks, size_t checks_sz,
          const struct hyperdex_client_map_attribute* mapattrs, size_t mapattrs_sz,
          enum hyperdex_client_returncode* status);
Parameters:  Returns: 
12.1.11.52 map_atomic_mod

Store the value of the key-value pair modulo the specified number for each map.

Behavior:  Definition: 
  int64_t hyperdex_client_map_atomic_mod(struct hyperdex_client* client,
          const char* space,
          const char* key, size_t key_sz,
          const struct hyperdex_client_map_attribute* mapattrs, size_t mapattrs_sz,
          enum hyperdex_client_returncode* status);
Parameters:  Returns: 
12.1.11.53 cond_map_atomic_mod

Conditionally store the value of the key-value pair modulo the specified number for each map.

Behavior:  Definition: 
  int64_t hyperdex_client_cond_map_atomic_mod(struct hyperdex_client* client,
          const char* space,
          const char* key, size_t key_sz,
          const struct hyperdex_client_attribute_check* checks, size_t checks_sz,
          const struct hyperdex_client_map_attribute* mapattrs, size_t mapattrs_sz,
          enum hyperdex_client_returncode* status);
Parameters:  Returns: 
12.1.11.54 map_atomic_and

Store the bitwise AND of the value of the key-value pair and the specified number for each map.

Behavior:  Definition: 
  int64_t hyperdex_client_map_atomic_and(struct hyperdex_client* client,
          const char* space,
          const char* key, size_t key_sz,
          const struct hyperdex_client_map_attribute* mapattrs, size_t mapattrs_sz,
          enum hyperdex_client_returncode* status);
Parameters:  Returns: 
12.1.11.55 cond_map_atomic_and

Conditionally store the bitwise AND of the value of the key-value pair and the specified number for each map.

Behavior:  Definition: 
  int64_t hyperdex_client_cond_map_atomic_and(struct hyperdex_client* client,
          const char* space,
          const char* key, size_t key_sz,
          const struct hyperdex_client_attribute_check* checks, size_t checks_sz,
          const struct hyperdex_client_map_attribute* mapattrs, size_t mapattrs_sz,
          enum hyperdex_client_returncode* status);
Parameters:  Returns: 
12.1.11.56 map_atomic_or

Store the bitwise OR of the value of the key-value pair and the specified number for each map.

Behavior:  Definition: 
  int64_t hyperdex_client_map_atomic_or(struct hyperdex_client* client,
          const char* space,
          const char* key, size_t key_sz,
          const struct hyperdex_client_map_attribute* mapattrs, size_t mapattrs_sz,
          enum hyperdex_client_returncode* status);
Parameters:  Returns: 
12.1.11.57 cond_map_atomic_or

Conditionally store the bitwise OR of the value of the key-value pair and the specified number for each map.

Behavior:  Definition: 
  int64_t hyperdex_client_cond_map_atomic_or(struct hyperdex_client* client,
          const char* space,
          const char* key, size_t key_sz,
          const struct hyperdex_client_attribute_check* checks, size_t checks_sz,
          const struct hyperdex_client_map_attribute* mapattrs, size_t mapattrs_sz,
          enum hyperdex_client_returncode* status);
Parameters:  Returns: 
12.1.11.58 map_atomic_xor

Store the bitwise XOR of the value of the key-value pair and the specified number for each map.

Behavior:  Definition: 
  int64_t hyperdex_client_map_atomic_xor(struct hyperdex_client* client,
          const char* space,
          const char* key, size_t key_sz,
          const struct hyperdex_client_map_attribute* mapattrs, size_t mapattrs_sz,
          enum hyperdex_client_returncode* status);
Parameters:  Returns: 
12.1.11.59 cond_map_atomic_xor

Conditionally store the bitwise XOR of the value of the key-value pair and the specified number for each map.

Behavior:  Definition: 
  int64_t hyperdex_client_cond_map_atomic_xor(struct hyperdex_client* client,
          const char* space,
          const char* key, size_t key_sz,
          const struct hyperdex_client_attribute_check* checks, size_t checks_sz,
          const struct hyperdex_client_map_attribute* mapattrs, size_t mapattrs_sz,
          enum hyperdex_client_returncode* status);
Parameters:  Returns: 
12.1.11.60 map_string_prepend

Prepend the specified string to the value of the key-value pair for each map.

Behavior:  Definition: 
  int64_t hyperdex_client_map_string_prepend(struct hyperdex_client* client,
          const char* space,
          const char* key, size_t key_sz,
          const struct hyperdex_client_map_attribute* mapattrs, size_t mapattrs_sz,
          enum hyperdex_client_returncode* status);
Parameters:  Returns: 
12.1.11.61 cond_map_string_prepend

Conditionally prepend the specified string to the value of the key-value pair for each map.

Behavior:  Definition: 
  int64_t hyperdex_client_cond_map_string_prepend(struct hyperdex_client* client,
          const char* space,
          const char* key, size_t key_sz,
          const struct hyperdex_client_attribute_check* checks, size_t checks_sz,
          const struct hyperdex_client_map_attribute* mapattrs, size_t mapattrs_sz,
          enum hyperdex_client_returncode* status);
Parameters:  Returns: 
12.1.11.62 map_string_append

Append the specified string to the value of the key-value pair for each map.

Behavior:  Definition: 
  int64_t hyperdex_client_map_string_append(struct hyperdex_client* client,
          const char* space,
          const char* key, size_t key_sz,
          const struct hyperdex_client_map_attribute* mapattrs, size_t mapattrs_sz,
          enum hyperdex_client_returncode* status);
Parameters:  Returns: 
12.1.11.63 cond_map_string_append

Conditionally append the specified string to the value of the key-value pair for each map.

Behavior:  Definition: 
  int64_t hyperdex_client_cond_map_string_append(struct hyperdex_client* client,
          const char* space,
          const char* key, size_t key_sz,
          const struct hyperdex_client_attribute_check* checks, size_t checks_sz,
          const struct hyperdex_client_map_attribute* mapattrs, size_t mapattrs_sz,
          enum hyperdex_client_returncode* status);
Parameters:  Returns: 
12.1.11.64 search

Return all objects that match the specified checks.

Behavior:  Definition: 
  int64_t hyperdex_client_search(struct hyperdex_client* client,
          const char* space,
          const struct hyperdex_client_attribute_check* checks, size_t checks_sz,
          enum hyperdex_client_returncode* status,
          const struct hyperdex_client_attribute** attrs, size_t* attrs_sz);
Parameters:  Returns: 
12.1.11.65 search_describe

Return a human-readable string suitable for debugging search internals. This API is only really relevant for debugging the internals of search. Definition: 

  int64_t hyperdex_client_search_describe(struct hyperdex_client* client,
          const char* space,
          const struct hyperdex_client_attribute_check* checks, size_t checks_sz,
          enum hyperdex_client_returncode* status,
          const char** description);
Parameters:  Returns: 
12.1.11.66 sorted_search

Return all objects that match the specified checks, sorted according to attr.

Behavior:  Definition: 
  int64_t hyperdex_client_sorted_search(struct hyperdex_client* client,
          const char* space,
          const struct hyperdex_client_attribute_check* checks, size_t checks_sz,
          const char* sort_by,
          uint64_t limit,
          int maxmin,
          enum hyperdex_client_returncode* status,
          const struct hyperdex_client_attribute** attrs, size_t* attrs_sz);
Parameters:  Returns: 
12.1.11.67 group_del

Asynchronously delete all objects that match the specified checks.

Behavior:  Definition: 
  int64_t hyperdex_client_group_del(struct hyperdex_client* client,
          const char* space,
          const struct hyperdex_client_attribute_check* checks, size_t checks_sz,
          enum hyperdex_client_returncode* status);
Parameters:  Returns: 
12.1.11.68 count

Count the number of objects that match the specified checks.

Behavior:  Definition: 
  int64_t hyperdex_client_count(struct hyperdex_client* client,
          const char* space,
          const struct hyperdex_client_attribute_check* checks, size_t checks_sz,
          enum hyperdex_client_returncode* status,
          uint64_t* count);
Parameters:  Returns: 

12.1.12 Working with Signals

The HyperDex client library is signal-safe. Should a signal interrupt the client during a blocking operation, it will return HYPERDEX_CLIENT_INTERRUPTED.

12.1.13 Working with Threads

The HyperDex client library is fully reentrant. Instances of struct hyperdex_client and their associated state may be accessed from multiple threads, provided that the application employes its own synchronization that provides mutual exclusion.

Put simply, a multi-threaded application should protect each struct hyperdex_client instance with a mutex or lock to ensure correct operation.

12.2 Admin Library

12.2.1 Operations

12.2.1.1 read_only

Change the cluster to and from read-only mode. Definition: 

  int64_t hyperdex_admin_read_only(struct hyperdex_admin* admin,
          int ro,
          enum hyperdex_admin_returncode* status);
Parameters:  Returns: 
12.2.1.2 wait_until_stable

Wait until the cluster is stable. The cluster is considered stable when all servers acknowledge the current configuration, and all initiated in previous configurations complete. Definition: 

  int64_t hyperdex_admin_wait_until_stable(struct hyperdex_admin* admin,
          enum hyperdex_admin_returncode* status);
Parameters:  Returns: 
12.2.1.3 fault_tolerance

Change the fault tolerance of space to the specified fault tolerance threshold. Definition: 

  int64_t hyperdex_admin_fault_tolerance(struct hyperdex_admin* admin,
          const char* space,
          uint64_t ft,
          enum hyperdex_admin_returncode* status);
Parameters:  Returns: 
12.2.1.4 validate_space

Validate the provided space description. Definition: 

  int hyperdex_admin_validate_space(struct hyperdex_admin* admin,
          const char* description,
          enum hyperdex_admin_returncode* status);
Parameters:  Returns: 
12.2.1.5 add_space

Add a new space to the cluster, using the provided space description. Definition: 

  int64_t hyperdex_admin_add_space(struct hyperdex_admin* admin,
          const char* description,
          enum hyperdex_admin_returncode* status);
Parameters:  Returns: 
12.2.1.6 rm_space

Remove space from the configuration and make it inaccessible to future operations. Definition: 

  int64_t hyperdex_admin_rm_space(struct hyperdex_admin* admin,
          const char* space,
          enum hyperdex_admin_returncode* status);
Parameters:  Returns: 
12.2.1.7 mv_space

Move space from name source to name target. This is a metadata operation and has the same cost as add_space, even for populated spaces. Definition: 

  int64_t hyperdex_admin_mv_space(struct hyperdex_admin* admin,
          const char* source,
          const char* target,
          enum hyperdex_admin_returncode* status);
Parameters:  Returns: 
12.2.1.8 list_spaces

List all spaces held by the cluster. Definition: 

  int64_t hyperdex_admin_list_spaces(struct hyperdex_admin* admin,
          enum hyperdex_admin_returncode* status,
          const char** spaces);
Parameters:  Returns: 
12.2.1.9 list_indices

XXX Definition: 

  int64_t hyperdex_admin_list_indices(struct hyperdex_admin* admin,
          const char* space,
          enum hyperdex_admin_returncode* status,
          const char** indexes);
Parameters:  Returns: 
12.2.1.10 list_subspaces

XXX Definition: 

  int64_t hyperdex_admin_list_subspaces(struct hyperdex_admin* admin,
          const char* space,
          enum hyperdex_admin_returncode* status,
          const char** subspaces);
Parameters:  Returns: 
12.2.1.11 add_index

Add a new index on a HyperDex attribute or document Definition: 

  int64_t hyperdex_admin_add_index(struct hyperdex_admin* admin,
          const char* space,
          const char* attribute,
          enum hyperdex_admin_returncode* status);
Parameters:  Returns: 
12.2.1.12 rm_index

Remove an existing index Definition: 

  int64_t hyperdex_admin_rm_index(struct hyperdex_admin* admin,
          uint64_t idxid,
          enum hyperdex_admin_returncode* status);
Parameters:  Returns: 
12.2.1.13 server_register

Manually register a new server with token bound to address. Definition: 

  int64_t hyperdex_admin_server_register(struct hyperdex_admin* admin,
          uint64_t token,
          const char* address,
          enum hyperdex_admin_returncode* status);
Parameters:  Returns: 
12.2.1.14 server_online

Manually set server token to state AVAILABLE. Definition: 

  int64_t hyperdex_admin_server_online(struct hyperdex_admin* admin,
          uint64_t token,
          enum hyperdex_admin_returncode* status);
Parameters:  Returns: 
12.2.1.15 server_offline

Manually mark server token as OFFLINE. Definition: 

  int64_t hyperdex_admin_server_offline(struct hyperdex_admin* admin,
          uint64_t token,
          enum hyperdex_admin_returncode* status);
Parameters:  Returns: 
12.2.1.16 server_forget

Completely remove all state associated token from the cluster. Definition: 

  int64_t hyperdex_admin_server_forget(struct hyperdex_admin* admin,
          uint64_t token,
          enum hyperdex_admin_returncode* status);
Parameters:  Returns: 
12.2.1.17 server_kill

Manually change server token into the KILLED state. Definition: 

  int64_t hyperdex_admin_server_kill(struct hyperdex_admin* admin,
          uint64_t token,
          enum hyperdex_admin_returncode* status);
Parameters:  Returns: 
12.2.1.18 backup

Initiate a cluster-wide backup named backup. Definition: 

  int64_t hyperdex_admin_backup(struct hyperdex_admin* admin,
          const char* backup,
          enum hyperdex_admin_returncode* status,
          const char** backups);
Parameters:  Returns: 
12.2.1.19 enable_perf_counters

Start collecting performance counters from all servers in the cluster. Definition: 

  int64_t hyperdex_admin_enable_perf_counters(struct hyperdex_admin* admin,
          enum hyperdex_admin_returncode* status,
          struct hyperdex_admin_perf_counter* pc);
Parameters:  Returns: 
12.2.1.20 disable_perf_counters

Stop collecting performance counters from all servers in the cluster. Definition: 

  void hyperdex_admin_disable_perf_counters(struct hyperdex_admin* admin);
Parameters:  Returns:  Nothing