Navigation

C/C++ API

The C API provides programmers with the most efficient way to access a HyperDex cluster. For this reason, the C API is used to implement scripting language APIs, and high performance applications. Where applicable, C++ names for functions are indicated. We ask that all custom benchmarks utilize the C API when other systems use native APIs as well.

Types

hyperclient

An opaque type containing all information about a single HyperDex client. An instance of hyperclient will maintain connections to the HyperDex coordinator, and HyperDex daemons.

This class exists in C++ as well.

See also

hyperclient_create(), hyperclient_destroy()

hyperdatatype

An enum indicating the type of a HyperDex attribute. Valid values are:

HYPERDATATYPE_STRING:
The data is a byte string consisting of uninterpreted data.
HYPERDATATYPE_INT64:
The data is interpreted as a signed, 64-bit little-endian integer. HyperDex will ignore trailing NULL bytes (they don’t impact the integer’s number), and will ignore any bytes beyond the first 8.
HYPERDATATYPE_GARBAGE:
There was an internal error which leaves the API unable to interpret the type of an object. This indicates an internal error within the HyperDex client library which should be fixed.

The C++ API uses this type as-is.

hyperclient_attribute

A struct representing one attribute of an object. Each attribute corresponds to one dimension in the hyperspace. The members of this struct are:

const char* hyperclient_attribute.attr

A NULL-terminated C-string containing the human-readable name assigned to the attribute at subspace creation.

const char* hyperclient_attribute.value

The bytes to be used for the attribute. These bytes will be interpreted by HyperDex according to the datatype field. This field is not NULL-terminated because its length is defined in value_sz.

size_t hyperclient_attribute.value_sz

The number of bytes pointed to by value.

hyperclient_datatype hyperclient_attribute.datatype

The manner in which HyperDex should interpret the contents of value. This field must match the type specified for attr at the time the space was defined.

The C++ API uses this type as-is.

hyperclient_range_query

A struct representing one element of a range query. The members of this struct are:

const char* hyperclient_range_query.attr

A NULL-terminated C-string containing the human-readable name assigned to the attribute at subspace creation.

uint64_t hyperclient_range_query.lower

The lower bound on objects matching the range query. All objects which match the query will have attr be greater than or equal to lower.

uint64_t hyperclient_range_query.upper

The upper bound on objects matching the range query. All objects which match the query will have attr be strictly less than upper.

The C++ API uses this type as-is.

See also

hyperclient_search()

hyperclient_returncode

An enum indicating the result of an operation. Valid values are:

HYPERCLIENT_SUCCESS:
The operation completed successfully. For operations which return objects, there is an object to be read.
HYPERCLIENT_NOTFOUND:
The operation completed successfully, but there was no object to return or operate on.
HYPERCLIENT_SEARCHDONE:

The indicated search operation has completed.

See also

hyperclient_search()

HYPERCLIENT_CMPFAIL:

A conditional operation failed its comparison.

See also

hyperclient_cond_put()

HYPERCLIENT_UNKNOWNSPACE:
The space specified does not exist.
HYPERCLIENT_COORDFAIL:
The client library has lost contact with the coordinator.
HYPERCLIENT_SERVERERROR:
A server has malfunctioned. This indicates the existence of a bug.
HYPERCLIENT_CONNECTFAIL:
A connection to a server has failed.
HYPERCLIENT_DISCONNECT:
A server has disconnected from the client library.
HYPERCLIENT_RECONFIGURE:
The operation failed because the host contacted for the operation changed identities part way through the operation.
HYPERCLIENT_LOGICERROR:
This indicates a bug in the client library.
HYPERCLIENT_TIMEOUT:

The requested operation has exceeded its timeout, and is returning without completing any work.

See also

hyperclient_loop()

HYPERCLIENT_UNKNOWNATTR:

The attribute is not one of the attributes which define the space.

See also

hyperclient_attribute.attr

HYPERCLIENT_DUPEATTR:

An attribute is specified twice.

See also

hyperclient_attribute.attr

HYPERCLIENT_SEEERRNO:
The errno variable will have more information about the failure.
HYPERCLIENT_NONEPENDING:

Loop was called, but no operations are pending.

See also

hyperclient_loop()

HYPERCLIENT_DONTUSEKEY:

The key was used as part of an equality search. The result of the search will be equivalent to a GET, so a get should be performed instead.

See also

hyperclient_get(), hyperclient_search()

HYPERCLIENT_WRONGTYPE:

There was a type mismatch.

See also

hyperclient_attribute.datatype

HYPERCLIENT_EXCEPTION:
The underlying C code threw an exception that was masked to prevent it from propagating up a C call stack. This indicates a bug in the client library.
HYPERCLIENT_ZERO:
A value usable for testing for uninitialized variables.
HYPERCLIENT_A:
A value usable for testing for uninitialized variables.
HYPERCLIENT_B:
A value usable for testing for uninitialized variables.

The C++ API uses this type as-is.

Functions

hyperclient* hyperclient_create(const char* coordinator, in_port_t port)

Return a hyperclient instance. The caller is responsible for releasing all resources held by this instance by calling hyperclient_destroy().

coordinator:
A string containing the IP of the coordinator for the HyperDex cluster.
port:
A number containing the port of the coordinator for the HyperDex cluster.

The C++ API provides a constructor for hyperclient which takes the same arguments and performs the same functionality.

See also

hyperclient, hyperclient_destroy()

void hyperclient_destroy(struct hyperclient* client)

Free all resources associated with the hyperclient pointed to by client.

client:
The hyperclient instance to be freed.

The C++ API provides a destructor for hyperclient in place of this call.

See also

hyperclient, hyperclient_create()

int64_t hyperclient_get(struct hyperclient* client, const char* space, const char* key, size_t key_sz, enum hyperclient_returncode* status, struct hyperclient_attribute** attrs, size_t* attrs_sz)

A get request retrieves an object from a specific space using the object’s key. If the object exists in the space at the time of the request, it will be returned; otherwise, the API will indicate that the object was not found.

Consistency:

A get request will always see the result of all complete put requests.

This operation is totally ordered with respect to all get, put, cond_put, delete and other atomic operations.

Efficiency:
The dominating cost of a get is one network round trip for cached objects, and one disk read for uncached objects.

On success, the integer returned will be a positive integer unique to this request. The request will be considered complete when hyperclient_loop() returns the same ID. If the integer returned is negative, it indicates an error generating the request, and *status contains the reason why.

client:
An initialized hyperclient instance.
space:
A NULL-terminated C-string containing the name of the space to retrieve the object from.
key:
A sequence of bytes to be used as the key. This pointer must remain valid for the duration of the call.
key_sz:
The number of bytes pointed to by key.
status:
A return value in which the result of the operation will be stored. If this function returns successfully, this pointer must remain valid until hyperclient_loop() returns the same ID returned by this function.
attrs:

A return value in which the object (if any) will be stored. This value will be changed if and only if *status is HYPERCLIENT_SUCCESS. If this function returns successfully, this pointer must remain valid until hyperclient_loop() returns the same ID returned by this function. This returned value must be released with a call to hyperclient_destroy_attrs().

See also

hyperclient_attribute, hyperclient_destroy_attrs()

attrs_sz:
The number of hyperclient_attribute instances returned in attrs. This value will be changed if and only if *status is HYPERCLIENT_SUCCESS. If this function returns successfully, this pointer must remain valid until hyperclient_loop() returns the same ID returned by this function.

The C++ API provides hyperclient::get in addition to this call.

int64_t hyperclient_put(struct hyperclient* client, const char* space, const char* key, size_t key_sz, const struct hyperclient_attribute* attrs, size_t attrs_sz, enum hyperclient_returncode* status)

A put request creates or updates the attributes of an object stored in a specific space under a specific key. Only those attributes specified will be affected by the put operation. If the object does not exist, it will be created, and all specified attributes will be set to the values provided. All other attributes will be initialized to their default state.

Consistency:

put requests to the same key will be observed in the same order by all clients. All get requests which execute after a given put request completes will see the result of that put, or of a later operation which superseded it.

This operation is totally ordered with respect to all get, put, cond_put, delete and other atomic operations.

Efficiency:
The dominating cost of a put is one network round trip per replica for cached objects, and one disk read per replica for uncached objects.

On success, the integer returned will be a positive integer unique to this request. The request will be considered complete when hyperclient_loop() returns the same ID. If the integer returned is negative, it indicates an error generating the request, and *status contains the reason why. HYPERCLIENT_UNKNOWNATTR, HYPERCLIENT_WRONGTYPE and HYPERCLIENT_DUPEATTR indicate which attribute caused the error by returning -1 - idx_of_bad_attr.

client:
An initialized hyperclient instance.
space:
A NULL-terminated C-string containing the name of the space to retrieve the object from.
key:
A sequence of bytes to be used as the key. This pointer must remain valid for the duration of the call.
key_sz:
The number of bytes pointed to by key.
attrs:
The attributes to be changed on the object. This pointer must remain valid for the duration of the call.
attrs_sz:
THe number of attributes pointed to by attrs.
status:
A return value in which the result of the operation will be stored. If this function returns successfully, this pointer must remain valid until hyperclient_loop() returns the same ID returned by this function.

The C++ API provides hyperclient::put in place of this call.

int64_t hyperclient_cond_put(struct hyperclient* client, const char* space, const char* key, size_t key_sz, const struct hyperclient_attribute* condattrs, size_t condattrs_sz, const struct hyperclient_attribute* attrs, size_t attrs_sz, enum hyperclient_returncode* status)

A cond_put request creates or updates the attributes of an object stored in a specific space under a specific key if and only if certain attributes match the specified condition.. Only those attributes specified will be affected by the cond_put operation. If the object does not exist, the operation will fail. All unspecified attributes will be left to their current values.

Consistency:
cond_put requests to the same key will be observed in the same order by all clients. All get requests which execute after a given cond_put request completes will see the result of that cond_put, or of a later operation which superseded it.
Efficiency:
The dominating cost of a cond_put is the same as a put when the comparison succeeds. If the comparison fails, the cost is the same as a get.

On success, the integer returned will be a positive integer unique to this request. The request will be considered complete when hyperclient_loop() returns the same ID. If the integer returned is negative, it indicates an error generating the request, and *status contains the reason why. HYPERCLIENT_UNKNOWNATTR, HYPERCLIENT_WRONGTYPE and HYPERCLIENT_DUPEATTR indicate which attribute caused the error by returning -1 - idx_of_bad_attr.

client:
An initialized hyperclient instance.
space:
A NULL-terminated C-string containing the name of the space to retrieve the object from.
key:
A sequence of bytes to be used as the key. This pointer must remain valid for the duration of the call.
key_sz:
The number of bytes pointed to by key.
condattrs:
The attributes to be compared against. All attributes must match for the CONDITIONAL PUT to be successful. This pointer must remain valid for the duration of the call.
condattrs_sz:
THe number of attributes pointed to by condattrs.
attrs:
The attributes to be changed on the object. This pointer must remain valid for the duration of the call.
attrs_sz:
THe number of attributes pointed to by attrs.
status:
A return value in which the result of the operation will be stored. If this function returns successfully, this pointer must remain valid until hyperclient_loop() returns the same ID returned by this function.

The C++ API provides hyperclient::cond_put in place of this call.

int64_t hyperclient_del(struct hyperclient* client, const char* space, const char* key, size_t key_sz, enum hyperclient_returncode* status)

A del request removes an object identified by a key from the specified space. If the object does not exist, the operation will do nothing.

Consistency:

del requests to the same key will be observed in the same order by all clients. All get requests which execute after a given del request completes will see the result of that del, or of a later operation which superseded it.

This operation is totally ordered with respect to all get, put, cond_put, delete and other atomic operations.

Efficiency:
The dominating cost of a del is one network round trip per replica for cached objects, and one disk read per replica for uncached objects.

On success, the integer returned will be a positive integer unique to this request. The request will be considered complete when hyperclient_loop() returns the same ID. If the integer returned is negative, it indicates an error generating the request, and *status contains the reason why.

client:
An initialized hyperclient instance.
space:
A NULL-terminated C-string containing the name of the space to retrieve the object from.
key:
A sequence of bytes to be used as the key. This pointer must remain valid for the duration of the call.
key_sz:
The number of bytes pointed to by key.
status:
A return value in which the result of the operation will be stored. If this function returns successfully, this pointer must remain valid until hyperclient_loop() returns the same ID returned by this function.

The C++ API provides hyperclient::del in place of this call.

int64_t hyperclient_atomic_add(struct hyperclient* client, const char* space, const char* key, size_t key_sz, const struct hyperclient_attribute* attrs, size_t attrs_sz, enum hyperclient_returncode* status)

An atomic_add request adds the amount specified to the value of each attribute specified by the request. The attributes will be modified atomically without interference from other operations.

Consistency:

atomic_add requests to the same key will be observed in the same order by all clients. All get requests which execute after a given atomic_add request completes will see the results of that atomic_add, or of a later operation which superseded it.

This operation is totally ordered with respect to all get, put, cond_put, delete and other atomic operations.

Efficiency:
The dominating cost of an atomic_add is the same as a put.

On success, the integer returned will be a positive integer unique to this request. The request will be considered complete when hyperclient_loop() returns the same ID. If the integer returned is negative, it indicates an error generating the request, and *status contains the reason why. HYPERCLIENT_UNKNOWNATTR, HYPERCLIENT_WRONGTYPE and HYPERCLIENT_DUPEATTR indicate which attribute caused the error by returning -1 - idx_of_bad_attr.

client:
An initialized hyperclient instance.
space:
A NULL-terminated C-string containing the name of the space to retrieve the object from.
key:
A sequence of bytes to be used as the key. This pointer must remain valid for the duration of the call.
key_sz:
The number of bytes pointed to by key.
attrs:
The set of attributes to be changed. Each hyperclient_attribute.value field in attrs will be used to atomically modify the specified attribute, thus allowing several attributes to be changed in different ways. This pointer must remain valid for the duration of the call.
attrs_sz:
The number of attributes pointed to by attrs.
status:
A return value in which the result of the operation will be stored. If this function returns successfully, this pointer must remain valid until hyperclient_loop() returns the same ID returned by this function.

The C++ API provides hyperclient::atomic_add in place of this call.

int64_t hyperclient_atomic_sub(struct hyperclient* client, const char* space, const char* key, size_t key_sz, const struct hyperclient_attribute* attrs, size_t attrs_sz, enum hyperclient_returncode* status)

An atomic_sub request subtracts the amount specified from the value of each attribute specified by the request. The attributes will be modified atomically without interference from other operations.

Consistency:

atomic_sub requests to the same key will be observed in the same order by all clients. All get requests which execute after a given atomic_sub request completes will see the results of that atomic_sub, or of a later operation which superseded it.

This operation is totally ordered with respect to all get, put, cond_put, delete and other atomic operations.

Efficiency:
The dominating cost of an atomic_sub is the same as a put.

On success, the integer returned will be a positive integer unique to this request. The request will be considered complete when hyperclient_loop() returns the same ID. If the integer returned is negative, it indicates an error generating the request, and *status contains the reason why. HYPERCLIENT_UNKNOWNATTR, HYPERCLIENT_WRONGTYPE and HYPERCLIENT_DUPEATTR indicate which attribute caused the error by returning -1 - idx_of_bad_attr.

client:
An initialized hyperclient instance.
space:
A NULL-terminated C-string containing the name of the space to retrieve the object from.
key:
A sequence of bytes to be used as the key. This pointer must remain valid for the duration of the call.
key_sz:
The number of bytes pointed to by key.
attrs:
The set of attributes to be changed. Each hyperclient_attribute.value field in attrs will be used to atomically modify the specified attribute, thus allowing several attributes to be changed in different ways. This pointer must remain valid for the duration of the call.
attrs_sz:
The number of attributes pointed to by attrs.
status:
A return value in which the result of the operation will be stored. If this function returns successfully, this pointer must remain valid until hyperclient_loop() returns the same ID returned by this function.

The C++ API provides hyperclient::atomic_sub in place of this call.

int64_t hyperclient_atomic_mul(struct hyperclient* client, const char* space, const char* key, size_t key_sz, const struct hyperclient_attribute* attrs, size_t attrs_sz, enum hyperclient_returncode* status)

An atomic_mul request multiplies the amount specified by the value of each attribute specified by the request. The attributes will be modified atomically without interference from other operations.

Consistency:

atomic_mul requests to the same key will be observed in the same order by all clients. All get requests which execute after a given atomic_mul request completes will see the results of that atomic_mul, or of a later operation which superseded it.

This operation is totally ordered with respect to all get, put, cond_put, delete and other atomic operations.

Efficiency:
The dominating cost of an atomic_mul is the same as a put.

On success, the integer returned will be a positive integer unique to this request. The request will be considered complete when hyperclient_loop() returns the same ID. If the integer returned is negative, it indicates an error generating the request, and *status contains the reason why. HYPERCLIENT_UNKNOWNATTR, HYPERCLIENT_WRONGTYPE and HYPERCLIENT_DUPEATTR indicate which attribute caused the error by returning -1 - idx_of_bad_attr.

client:
An initialized hyperclient instance.
space:
A NULL-terminated C-string containing the name of the space to retrieve the object from.
key:
A sequence of bytes to be used as the key. This pointer must remain valid for the duration of the call.
key_sz:
The number of bytes pointed to by key.
attrs:
The set of attributes to be changed. Each hyperclient_attribute.value field in attrs will be used to atomically modify the specified attribute, thus allowing several attributes to be changed in different ways. This pointer must remain valid for the duration of the call.
attrs_sz:
The number of attributes pointed to by attrs.
status:
A return value in which the result of the operation will be stored. If this function returns successfully, this pointer must remain valid until hyperclient_loop() returns the same ID returned by this function.

The C++ API provides hyperclient::atomic_mul in place of this call.

int64_t hyperclient_atomic_div(struct hyperclient* client, const char* space, const char* key, size_t key_sz, const struct hyperclient_attribute* attrs, size_t attrs_sz, enum hyperclient_returncode* status)

An atomic_div request divides the value of each attribute specified by the request by the amount specified. The attributes will be modified atomically without interference from other operations.

Consistency:

atomic_div requests to the same key will be observed in the same order by all clients. All get requests which execute after a given atomic_div request completes will see the results of that atomic_div, or of a later operation which superseded it.

This operation is totally ordered with respect to all get, put, cond_put, delete and other atomic operations.

Efficiency:
The dominating cost of an atomic_div is the same as a put.

On success, the integer returned will be a positive integer unique to this request. The request will be considered complete when hyperclient_loop() returns the same ID. If the integer returned is negative, it indicates an error generating the request, and *status contains the reason why. HYPERCLIENT_UNKNOWNATTR, HYPERCLIENT_WRONGTYPE and HYPERCLIENT_DUPEATTR indicate which attribute caused the error by returning -1 - idx_of_bad_attr.

client:
An initialized hyperclient instance.
space:
A NULL-terminated C-string containing the name of the space to retrieve the object from.
key:
A sequence of bytes to be used as the key. This pointer must remain valid for the duration of the call.
key_sz:
The number of bytes pointed to by key.
attrs:
The set of attributes to be changed. Each hyperclient_attribute.value field in attrs will be used to atomically modify the specified attribute, thus allowing several attributes to be changed in different ways. This pointer must remain valid for the duration of the call.
attrs_sz:
The number of attributes pointed to by attrs.
status:
A return value in which the result of the operation will be stored. If this function returns successfully, this pointer must remain valid until hyperclient_loop() returns the same ID returned by this function.

The C++ API provides hyperclient::atomic_div in place of this call.

int64_t hyperclient_atomic_mod(struct hyperclient* client, const char* space, const char* key, size_t key_sz, const struct hyperclient_attribute* attrs, size_t attrs_sz, enum hyperclient_returncode* status)

An atomic_mod request computes the value of each attribute specified by the request modulo the amount specified. The attributes will be modified atomically without interference from other operations.

Consistency:

atomic_mod requests to the same key will be observed in the same order by all clients. All get requests which execute after a given atomic_mod request completes will see the results of that atomic_mod, or of a later operation which superseded it.

This operation is totally ordered with respect to all get, put, cond_put, delete and other atomic operations.

Efficiency:
The dominating cost of an atomic_mod is the same as a put.

On success, the integer returned will be a positive integer unique to this request. The request will be considered complete when hyperclient_loop() returns the same ID. If the integer returned is negative, it indicates an error generating the request, and *status contains the reason why. HYPERCLIENT_UNKNOWNATTR, HYPERCLIENT_WRONGTYPE and HYPERCLIENT_DUPEATTR indicate which attribute caused the error by returning -1 - idx_of_bad_attr.

client:
An initialized hyperclient instance.
space:
A NULL-terminated C-string containing the name of the space to retrieve the object from.
key:
A sequence of bytes to be used as the key. This pointer must remain valid for the duration of the call.
key_sz:
The number of bytes pointed to by key.
attrs:
The set of attributes to be changed. Each hyperclient_attribute.value field in attrs will be used to atomically modify the specified attribute, thus allowing several attributes to be changed in different ways. This pointer must remain valid for the duration of the call.
attrs_sz:
The number of attributes pointed to by attrs.
status:
A return value in which the result of the operation will be stored. If this function returns successfully, this pointer must remain valid until hyperclient_loop() returns the same ID returned by this function.

The C++ API provides hyperclient::atomic_mod in place of this call.

int64_t hyperclient_atomic_and(struct hyperclient* client, const char* space, const char* key, size_t key_sz, const struct hyperclient_attribute* attrs, size_t attrs_sz, enum hyperclient_returncode* status)

An atomic_and request stores the bitwise-and of the amount specified with the value of each attribute specified by the request. The attributes will be modified atomically without interference from other operations.

Consistency:

atomic_and requests to the same key will be observed in the same order by all clients. All get requests which execute after a given atomic_and request completes will see the results of that atomic_and, or of a later operation which superseded it.

This operation is totally ordered with respect to all get, put, cond_put, delete and other atomic operations.

Efficiency:
The dominating cost of an atomic_and is the same as a put.

On success, the integer returned will be a positive integer unique to this request. The request will be considered complete when hyperclient_loop() returns the same ID. If the integer returned is negative, it indicates an error generating the request, and *status contains the reason why. HYPERCLIENT_UNKNOWNATTR, HYPERCLIENT_WRONGTYPE and HYPERCLIENT_DUPEATTR indicate which attribute caused the error by returning -1 - idx_of_bad_attr.

client:
An initialized hyperclient instance.
space:
A NULL-terminated C-string containing the name of the space to retrieve the object from.
key:
A sequence of bytes to be used as the key. This pointer must remain valid for the duration of the call.
key_sz:
The number of bytes pointed to by key.
attrs:
The set of attributes to be changed. Each hyperclient_attribute.value field in attrs will be used to atomically modify the specified attribute, thus allowing several attributes to be changed in different ways. This pointer must remain valid for the duration of the call.
attrs_sz:
The number of attributes pointed to by attrs.
status:
A return value in which the result of the operation will be stored. If this function returns successfully, this pointer must remain valid until hyperclient_loop() returns the same ID returned by this function.

The C++ API provides hyperclient::atomic_and in place of this call.

int64_t hyperclient_atomic_or(struct hyperclient* client, const char* space, const char* key, size_t key_sz, const struct hyperclient_attribute* attrs, size_t attrs_sz, enum hyperclient_returncode* status)

An atomic_or request stores the bitwise-or of the amount specified with the value of each attribute specified by the request. The attributes will be modified atomically without interference from other operations.

Consistency:

atomic_or requests to the same key will be observed in the same order by all clients. All get requests which execute after a given atomic_or request completes will see the results of that atomic_or, or of a later operation which superseded it.

This operation is totally ordered with respect to all get, put, cond_put, delete and other atomic operations.

Efficiency:
The dominating cost of an atomic_or is the same as a put.

On success, the integer returned will be a positive integer unique to this request. The request will be considered complete when hyperclient_loop() returns the same ID. If the integer returned is negative, it indicates an error generating the request, and *status contains the reason why. HYPERCLIENT_UNKNOWNATTR, HYPERCLIENT_WRONGTYPE and HYPERCLIENT_DUPEATTR indicate which attribute caused the error by returning -1 - idx_of_bad_attr.

client:
An initialized hyperclient instance.
space:
A NULL-terminated C-string containing the name of the space to retrieve the object from.
key:
A sequence of bytes to be used as the key. This pointer must remain valid for the duration of the call.
key_sz:
The number of bytes pointed to by key.
attrs:
The set of attributes to be changed. Each hyperclient_attribute.value field in attrs will be used to atomically modify the specified attribute, thus allowing several attributes to be changed in different ways. This pointer must remain valid for the duration of the call.
attrs_sz:
The number of attributes pointed to by attrs.
status:
A return value in which the result of the operation will be stored. If this function returns successfully, this pointer must remain valid until hyperclient_loop() returns the same ID returned by this function.

The C++ API provides hyperclient::atomic_or in place of this call.

int64_t hyperclient_atomic_xor(struct hyperclient* client, const char* space, const char* key, size_t key_sz, const struct hyperclient_attribute* attrs, size_t attrs_sz, enum hyperclient_returncode* status)

An atomic_xor request stores the bitwise-xor of the amount specified with the value of each attribute specified by the request. The attributes will be modified atomically without interference from other operations.

Consistency:

atomic_xor requests to the same key will be observed in the same order by all clients. All get requests which execute after a given atomic_xor request completes will see the results of that atomic_xor, or of a later operation which superseded it.

This operation is totally ordered with respect to all get, put, cond_put, delete and other atomic operations.

Efficiency:
The dominating cost of an atomic_xor is the same as a put.

On success, the integer returned will be a positive integer unique to this request. The request will be considered complete when hyperclient_loop() returns the same ID. If the integer returned is negative, it indicates an error generating the request, and *status contains the reason why. HYPERCLIENT_UNKNOWNATTR, HYPERCLIENT_WRONGTYPE and HYPERCLIENT_DUPEATTR indicate which attribute caused the error by returning -1 - idx_of_bad_attr.

client:
An initialized hyperclient instance.
space:
A NULL-terminated C-string containing the name of the space to retrieve the object from.
key:
A sequence of bytes to be used as the key. This pointer must remain valid for the duration of the call.
key_sz:
The number of bytes pointed to by key.
attrs:
The set of attributes to be changed. Each hyperclient_attribute.value field in attrs will be used to atomically modify the specified attribute, thus allowing several attributes to be changed in different ways. This pointer must remain valid for the duration of the call.
attrs_sz:
The number of attributes pointed to by attrs.
status:
A return value in which the result of the operation will be stored. If this function returns successfully, this pointer must remain valid until hyperclient_loop() returns the same ID returned by this function.

The C++ API provides hyperclient::atomic_xor in place of this call.

int64_t hyperclient_string_prepend(struct hyperclient* client, const char* space, const char* key, size_t key_sz, const struct hyperclient_attribute* attrs, size_t attrs_sz, enum hyperclient_returncode* status)

A string_prepend request prepends the specified string to the value of each attribute specified by the request. The attributes will be modified atomically without interference from other operations.

Consistency:

string_prepend requests to the same key will be observed in the same order by all clients. All get requests which execute after a given string_prepend request completes will see the results of that string_prepend, or of a later operation which superseded it.

This operation is totally ordered with respect to all get, put, cond_put, delete and other atomic operations.

Efficiency:
The dominating cost of an string_prepend is the same as a put.

On success, the integer returned will be a positive integer unique to this request. The request will be considered complete when hyperclient_loop() returns the same ID. If the integer returned is negative, it indicates an error generating the request, and *status contains the reason why. HYPERCLIENT_UNKNOWNATTR, HYPERCLIENT_WRONGTYPE and HYPERCLIENT_DUPEATTR indicate which attribute caused the error by returning -1 - idx_of_bad_attr.

client:
An initialized hyperclient instance.
space:
A NULL-terminated C-string containing the name of the space to retrieve the object from.
key:
A sequence of bytes to be used as the key. This pointer must remain valid for the duration of the call.
key_sz:
The number of bytes pointed to by key.
attrs:
The set of attributes to be changed. Each hyperclient_attribute.value field in attrs will be used to atomically modify the specified attribute, thus allowing several attributes to be changed in different ways. This pointer must remain valid for the duration of the call.
attrs_sz:
The number of attributes pointed to by attrs.
status:
A return value in which the result of the operation will be stored. If this function returns successfully, this pointer must remain valid until hyperclient_loop() returns the same ID returned by this function.

The C++ API provides hyperclient::string_prepend in place of this call.

int64_t hyperclient_string_append(struct hyperclient* client, const char* space, const char* key, size_t key_sz, const struct hyperclient_attribute* attrs, size_t attrs_sz, enum hyperclient_returncode* status)

A string_append request appends the specified string to the value of each attribute specified by the request. The attributes will be modified atomically without interference from other operations.

Consistency:

string_append requests to the same key will be observed in the same order by all clients. All get requests which execute after a given string_append request completes will see the results of that string_append, or of a later operation which superseded it.

This operation is totally ordered with respect to all get, put, cond_put, delete and other atomic operations.

Efficiency:
The dominating cost of an string_append is the same as a put.

On success, the integer returned will be a positive integer unique to this request. The request will be considered complete when hyperclient_loop() returns the same ID. If the integer returned is negative, it indicates an error generating the request, and *status contains the reason why. HYPERCLIENT_UNKNOWNATTR, HYPERCLIENT_WRONGTYPE and HYPERCLIENT_DUPEATTR indicate which attribute caused the error by returning -1 - idx_of_bad_attr.

client:
An initialized hyperclient instance.
space:
A NULL-terminated C-string containing the name of the space to retrieve the object from.
key:
A sequence of bytes to be used as the key. This pointer must remain valid for the duration of the call.
key_sz:
The number of bytes pointed to by key.
attrs:
The set of attributes to be changed. Each hyperclient_attribute.value field in attrs will be used to atomically modify the specified attribute, thus allowing several attributes to be changed in different ways. This pointer must remain valid for the duration of the call.
attrs_sz:
The number of attributes pointed to by attrs.
status:
A return value in which the result of the operation will be stored. If this function returns successfully, this pointer must remain valid until hyperclient_loop() returns the same ID returned by this function.

The C++ API provides hyperclient::string_append in place of this call.

int64_t hyperclient_list_lpush(struct hyperclient* client, const char* space, const char* key, size_t key_sz, const struct hyperclient_attribute* attrs, size_t attrs_sz, enum hyperclient_returncode* status)

A list_lpush request pushes the specified object to the head of the list of each attribute specified by the request. The attributes will be modified atomically without interference from other operations.

Consistency:

list_lpush requests to the same key will be observed in the same order by all clients. All get requests which execute after a given list_lpush request completes will see the results of that list_lpush, or of a later operation which superseded it.

This operation is totally ordered with respect to all get, put, cond_put, delete and other atomic operations.

Efficiency:
The dominating cost of an list_lpush is the same as a put.

On success, the integer returned will be a positive integer unique to this request. The request will be considered complete when hyperclient_loop() returns the same ID. If the integer returned is negative, it indicates an error generating the request, and *status contains the reason why. HYPERCLIENT_UNKNOWNATTR, HYPERCLIENT_WRONGTYPE and HYPERCLIENT_DUPEATTR indicate which attribute caused the error by returning -1 - idx_of_bad_attr.

client:
An initialized hyperclient instance.
space:
A NULL-terminated C-string containing the name of the space to retrieve the object from.
key:
A sequence of bytes to be used as the key. This pointer must remain valid for the duration of the call.
key_sz:
The number of bytes pointed to by key.
attrs:
The set of attributes to be changed. Each hyperclient_attribute.value field in attrs will be used to atomically modify the specified attribute, thus allowing several attributes to be changed in different ways. This pointer must remain valid for the duration of the call.
attrs_sz:
The number of attributes pointed to by attrs.
status:
A return value in which the result of the operation will be stored. If this function returns successfully, this pointer must remain valid until hyperclient_loop() returns the same ID returned by this function.

The C++ API provides hyperclient::list_lpush in place of this call.

int64_t hyperclient_list_rpush(struct hyperclient* client, const char* space, const char* key, size_t key_sz, const struct hyperclient_attribute* attrs, size_t attrs_sz, enum hyperclient_returncode* status)

A list_rpush request pushes the specified object to the tail of the list of each attribute specified by the request. The attributes will be modified atomically without interference from other operations.

Consistency:

list_rpush requests to the same key will be observed in the same order by all clients. All get requests which execute after a given list_rpush request completes will see the results of that list_rpush, or of a later operation which superseded it.

This operation is totally ordered with respect to all get, put, cond_put, delete and other atomic operations.

Efficiency:
The dominating cost of an list_rpush is the same as a put.

On success, the integer returned will be a positive integer unique to this request. The request will be considered complete when hyperclient_loop() returns the same ID. If the integer returned is negative, it indicates an error generating the request, and *status contains the reason why. HYPERCLIENT_UNKNOWNATTR, HYPERCLIENT_WRONGTYPE and HYPERCLIENT_DUPEATTR indicate which attribute caused the error by returning -1 - idx_of_bad_attr.

client:
An initialized hyperclient instance.
space:
A NULL-terminated C-string containing the name of the space to retrieve the object from.
key:
A sequence of bytes to be used as the key. This pointer must remain valid for the duration of the call.
key_sz:
The number of bytes pointed to by key.
attrs:
The set of attributes to be changed. Each hyperclient_attribute.value field in attrs will be used to atomically modify the specified attribute, thus allowing several attributes to be changed in different ways. This pointer must remain valid for the duration of the call.
attrs_sz:
The number of attributes pointed to by attrs.
status:
A return value in which the result of the operation will be stored. If this function returns successfully, this pointer must remain valid until hyperclient_loop() returns the same ID returned by this function.

The C++ API provides hyperclient::list_rpush in place of this call.

int64_t hyperclient_set_add(struct hyperclient* client, const char* space, const char* key, size_t key_sz, const struct hyperclient_attribute* attrs, size_t attrs_sz, enum hyperclient_returncode* status)

A set_add request adds a single element to a set or does nothing if the element is already in the set. The insertion will be atomic without interference from other operations.

Consistency:

set_add requests to the same key will be observed in the same order by all clients. All get requests which execute after a given set_add request completes will see the results of that set_add, or of a later operation which superseded it.

This operation is totally ordered with respect to all get, put, cond_put, delete and other atomic operations.

Efficiency:
The dominating cost of an set_add is the same as a put.

On success, the integer returned will be a positive integer unique to this request. The request will be considered complete when hyperclient_loop() returns the same ID. If the integer returned is negative, it indicates an error generating the request, and *status contains the reason why. HYPERCLIENT_UNKNOWNATTR, HYPERCLIENT_WRONGTYPE and HYPERCLIENT_DUPEATTR indicate which attribute caused the error by returning -1 - idx_of_bad_attr.

client:
An initialized hyperclient instance.
space:
A NULL-terminated C-string containing the name of the space to retrieve the object from.
key:
A sequence of bytes to be used as the key. This pointer must remain valid for the duration of the call.
key_sz:
The number of bytes pointed to by key.
attrs:
The set of attributes to be changed. Each hyperclient_attribute.value field in attrs will be used to atomically modify the specified attribute, thus allowing several attributes to be changed in different ways. This pointer must remain valid for the duration of the call.
attrs_sz:
The number of attributes pointed to by attrs.
status:
A return value in which the result of the operation will be stored. If this function returns successfully, this pointer must remain valid until hyperclient_loop() returns the same ID returned by this function.

The C++ API provides hyperclient::set_add in place of this call.

int64_t hyperclient_set_remove(struct hyperclient* client, const char* space, const char* key, size_t key_sz, const struct hyperclient_attribute* attrs, size_t attrs_sz, enum hyperclient_returncode* status)

A set_remove request removes a single element to a set, or does nothing if the element is not in the set. The removal will be atomic without interference from other operations.

Consistency:

set_remove requests to the same key will be observed in the same order by all clients. All get requests which execute after a given set_remove request completes will see the results of that set_remove, or of a later operation which superseded it.

This operation is totally ordered with respect to all get, put, cond_put, delete and other atomic operations.

Efficiency:
The dominating cost of an set_remove is the same as a put.

On success, the integer returned will be a positive integer unique to this request. The request will be considered complete when hyperclient_loop() returns the same ID. If the integer returned is negative, it indicates an error generating the request, and *status contains the reason why. HYPERCLIENT_UNKNOWNATTR, HYPERCLIENT_WRONGTYPE and HYPERCLIENT_DUPEATTR indicate which attribute caused the error by returning -1 - idx_of_bad_attr.

client:
An initialized hyperclient instance.
space:
A NULL-terminated C-string containing the name of the space to retrieve the object from.
key:
A sequence of bytes to be used as the key. This pointer must remain valid for the duration of the call.
key_sz:
The number of bytes pointed to by key.
attrs:
The set of attributes to be changed. Each hyperclient_attribute.value field in attrs will be used to atomically modify the specified attribute, thus allowing several attributes to be changed in different ways. This pointer must remain valid for the duration of the call.
attrs_sz:
The number of attributes pointed to by attrs.
status:
A return value in which the result of the operation will be stored. If this function returns successfully, this pointer must remain valid until hyperclient_loop() returns the same ID returned by this function.

The C++ API provides hyperclient::set_remove in place of this call.

int64_t hyperclient_set_intersect(struct hyperclient* client, const char* space, const char* key, size_t key_sz, const struct hyperclient_attribute* attrs, size_t attrs_sz, enum hyperclient_returncode* status)

A set_intersect performs set intersection, and stores the resulting set in the object. The intersection will be atomic without interference from other operations.

Consistency:

set_intersect requests to the same key will be observed in the same order by all clients. All get requests which execute after a given set_intersect request completes will see the results of that set_intersect, or of a later operation which superseded it.

This operation is totally ordered with respect to all get, put, cond_put, delete and other atomic operations.

Efficiency:
The dominating cost of an set_intersect is the same as a put.

On success, the integer returned will be a positive integer unique to this request. The request will be considered complete when hyperclient_loop() returns the same ID. If the integer returned is negative, it indicates an error generating the request, and *status contains the reason why. HYPERCLIENT_UNKNOWNATTR, HYPERCLIENT_WRONGTYPE and HYPERCLIENT_DUPEATTR indicate which attribute caused the error by returning -1 - idx_of_bad_attr.

client:
An initialized hyperclient instance.
space:
A NULL-terminated C-string containing the name of the space to retrieve the object from.
key:
A sequence of bytes to be used as the key. This pointer must remain valid for the duration of the call.
key_sz:
The number of bytes pointed to by key.
attrs:
The set of attributes to be changed. Each hyperclient_attribute.value field in attrs will be used to atomically modify the specified attribute, thus allowing several attributes to be changed in different ways. This pointer must remain valid for the duration of the call.
attrs_sz:
The number of attributes pointed to by attrs.
status:
A return value in which the result of the operation will be stored. If this function returns successfully, this pointer must remain valid until hyperclient_loop() returns the same ID returned by this function.

The C++ API provides hyperclient::set_intersect in place of this call.

int64_t hyperclient_set_union(struct hyperclient* client, const char* space, const char* key, size_t key_sz, const struct hyperclient_attribute* attrs, size_t attrs_sz, enum hyperclient_returncode* status)

A set_union performs set union, and stores the resulting set in the object. The union will be atomic without interference from other operations.

Consistency:

set_union requests to the same key will be observed in the same order by all clients. All get requests which execute after a given set_union request completes will see the results of that set_union, or of a later operation which superseded it.

This operation is totally ordered with respect to all get, put, cond_put, delete and other atomic operations.

Efficiency:
The dominating cost of an set_union is the same as a put.

On success, the integer returned will be a positive integer unique to this request. The request will be considered complete when hyperclient_loop() returns the same ID. If the integer returned is negative, it indicates an error generating the request, and *status contains the reason why. HYPERCLIENT_UNKNOWNATTR, HYPERCLIENT_WRONGTYPE and HYPERCLIENT_DUPEATTR indicate which attribute caused the error by returning -1 - idx_of_bad_attr.

client:
An initialized hyperclient instance.
space:
A NULL-terminated C-string containing the name of the space to retrieve the object from.
key:
A sequence of bytes to be used as the key. This pointer must remain valid for the duration of the call.
key_sz:
The number of bytes pointed to by key.
attrs:
The set of attributes to be changed. Each hyperclient_attribute.value field in attrs will be used to atomically modify the specified attribute, thus allowing several attributes to be changed in different ways. This pointer must remain valid for the duration of the call.
attrs_sz:
The number of attributes pointed to by attrs.
status:
A return value in which the result of the operation will be stored. If this function returns successfully, this pointer must remain valid until hyperclient_loop() returns the same ID returned by this function.

The C++ API provides hyperclient::set_union in place of this call.

int64_t hyperclient_map_atomic_add(struct hyperclient* client, const char* space, const char* key, size_t key_sz, const struct hyperclient_map_attribute* attrs, size_t attrs_sz, enum hyperclient_returncode* status)

An atomic_add request adds the amount specified to the value of each attribute specified by the request. The attributes will be modified atomically without interference from other operations.

Consistency:

atomic_add requests to the same key will be observed in the same order by all clients. All get requests which execute after a given atomic_add request completes will see the results of that atomic_add, or of a later operation which superseded it.

This operation is totally ordered with respect to all get, put, cond_put, delete and other atomic operations.

Efficiency:
The dominating cost of an atomic_add is the same as a put.

On success, the integer returned will be a positive integer unique to this request. The request will be considered complete when hyperclient_loop() returns the same ID. If the integer returned is negative, it indicates an error generating the request, and *status contains the reason why. HYPERCLIENT_UNKNOWNATTR, HYPERCLIENT_WRONGTYPE and HYPERCLIENT_DUPEATTR indicate which attribute caused the error by returning -1 - idx_of_bad_attr.

client:
An initialized hyperclient instance.
space:
A NULL-terminated C-string containing the name of the space to retrieve the object from.
key:
A sequence of bytes to be used as the key. This pointer must remain valid for the duration of the call.
key_sz:
The number of bytes pointed to by key.
attrs:
The set of attributes to be changed. Each struct will indicate a map on which to operate with hyperclient_attribute.attr and the key within that map with hyperclient_attribute.map_key. The hyperclient_attribute.value field will be used to atomically modify the specified attribute, thus allowing several attributes to be changed in different ways. This pointer must remain valid for the duration of the call.
attrs_sz:
The number of attributes pointed to by attrs.
status:
A return value in which the result of the operation will be stored. If this function returns successfully, this pointer must remain valid until hyperclient_loop() returns the same ID returned by this function.

The C++ API provides hyperclient::map_atomic_add in place of this call.

int64_t hyperclient_map_atomic_sub(struct hyperclient* client, const char* space, const char* key, size_t key_sz, const struct hyperclient_map_attribute* attrs, size_t attrs_sz, enum hyperclient_returncode* status)

An atomic_sub request subtracts the amount specified from the value of each attribute specified by the request. The attributes will be modified atomically without interference from other operations.

Consistency:

atomic_sub requests to the same key will be observed in the same order by all clients. All get requests which execute after a given atomic_sub request completes will see the results of that atomic_sub, or of a later operation which superseded it.

This operation is totally ordered with respect to all get, put, cond_put, delete and other atomic operations.

Efficiency:
The dominating cost of an atomic_sub is the same as a put.

On success, the integer returned will be a positive integer unique to this request. The request will be considered complete when hyperclient_loop() returns the same ID. If the integer returned is negative, it indicates an error generating the request, and *status contains the reason why. HYPERCLIENT_UNKNOWNATTR, HYPERCLIENT_WRONGTYPE and HYPERCLIENT_DUPEATTR indicate which attribute caused the error by returning -1 - idx_of_bad_attr.

client:
An initialized hyperclient instance.
space:
A NULL-terminated C-string containing the name of the space to retrieve the object from.
key:
A sequence of bytes to be used as the key. This pointer must remain valid for the duration of the call.
key_sz:
The number of bytes pointed to by key.
attrs:
The set of attributes to be changed. Each struct will indicate a map on which to operate with hyperclient_attribute.attr and the key within that map with hyperclient_attribute.map_key. The hyperclient_attribute.value field will be used to atomically modify the specified attribute, thus allowing several attributes to be changed in different ways. This pointer must remain valid for the duration of the call.
attrs_sz:
The number of attributes pointed to by attrs.
status:
A return value in which the result of the operation will be stored. If this function returns successfully, this pointer must remain valid until hyperclient_loop() returns the same ID returned by this function.

The C++ API provides hyperclient::map_atomic_sub in place of this call.

int64_t hyperclient_map_atomic_mul(struct hyperclient* client, const char* space, const char* key, size_t key_sz, const struct hyperclient_map_attribute* attrs, size_t attrs_sz, enum hyperclient_returncode* status)

An atomic_mul request multiplies the amount specified by the value of each attribute specified by the request. The attributes will be modified atomically without interference from other operations.

Consistency:

atomic_mul requests to the same key will be observed in the same order by all clients. All get requests which execute after a given atomic_mul request completes will see the results of that atomic_mul, or of a later operation which superseded it.

This operation is totally ordered with respect to all get, put, cond_put, delete and other atomic operations.

Efficiency:
The dominating cost of an atomic_mul is the same as a put.

On success, the integer returned will be a positive integer unique to this request. The request will be considered complete when hyperclient_loop() returns the same ID. If the integer returned is negative, it indicates an error generating the request, and *status contains the reason why. HYPERCLIENT_UNKNOWNATTR, HYPERCLIENT_WRONGTYPE and HYPERCLIENT_DUPEATTR indicate which attribute caused the error by returning -1 - idx_of_bad_attr.

client:
An initialized hyperclient instance.
space:
A NULL-terminated C-string containing the name of the space to retrieve the object from.
key:
A sequence of bytes to be used as the key. This pointer must remain valid for the duration of the call.
key_sz:
The number of bytes pointed to by key.
attrs:
The set of attributes to be changed. Each struct will indicate a map on which to operate with hyperclient_attribute.attr and the key within that map with hyperclient_attribute.map_key. The hyperclient_attribute.value field will be used to atomically modify the specified attribute, thus allowing several attributes to be changed in different ways. This pointer must remain valid for the duration of the call.
attrs_sz:
The number of attributes pointed to by attrs.
status:
A return value in which the result of the operation will be stored. If this function returns successfully, this pointer must remain valid until hyperclient_loop() returns the same ID returned by this function.

The C++ API provides hyperclient::map_atomic_mul in place of this call.

int64_t hyperclient_map_atomic_div(struct hyperclient* client, const char* space, const char* key, size_t key_sz, const struct hyperclient_map_attribute* attrs, size_t attrs_sz, enum hyperclient_returncode* status)

An atomic_div request divides the value of each attribute specified by the request by the amount specified. The attributes will be modified atomically without interference from other operations.

Consistency:

atomic_div requests to the same key will be observed in the same order by all clients. All get requests which execute after a given atomic_div request completes will see the results of that atomic_div, or of a later operation which superseded it.

This operation is totally ordered with respect to all get, put, cond_put, delete and other atomic operations.

Efficiency:
The dominating cost of an atomic_div is the same as a put.

On success, the integer returned will be a positive integer unique to this request. The request will be considered complete when hyperclient_loop() returns the same ID. If the integer returned is negative, it indicates an error generating the request, and *status contains the reason why. HYPERCLIENT_UNKNOWNATTR, HYPERCLIENT_WRONGTYPE and HYPERCLIENT_DUPEATTR indicate which attribute caused the error by returning -1 - idx_of_bad_attr.

client:
An initialized hyperclient instance.
space:
A NULL-terminated C-string containing the name of the space to retrieve the object from.
key:
A sequence of bytes to be used as the key. This pointer must remain valid for the duration of the call.
key_sz:
The number of bytes pointed to by key.
attrs:
The set of attributes to be changed. Each struct will indicate a map on which to operate with hyperclient_attribute.attr and the key within that map with hyperclient_attribute.map_key. The hyperclient_attribute.value field will be used to atomically modify the specified attribute, thus allowing several attributes to be changed in different ways. This pointer must remain valid for the duration of the call.
attrs_sz:
The number of attributes pointed to by attrs.
status:
A return value in which the result of the operation will be stored. If this function returns successfully, this pointer must remain valid until hyperclient_loop() returns the same ID returned by this function.

The C++ API provides hyperclient::map_atomic_div in place of this call.

int64_t hyperclient_map_atomic_mod(struct hyperclient* client, const char* space, const char* key, size_t key_sz, const struct hyperclient_map_attribute* attrs, size_t attrs_sz, enum hyperclient_returncode* status)

An atomic_mod request computes the value of each attribute specified by the request modulo the amount specified. The attributes will be modified atomically without interference from other operations.

Consistency:

atomic_mod requests to the same key will be observed in the same order by all clients. All get requests which execute after a given atomic_mod request completes will see the results of that atomic_mod, or of a later operation which superseded it.

This operation is totally ordered with respect to all get, put, cond_put, delete and other atomic operations.

Efficiency:
The dominating cost of an atomic_mod is the same as a put.

On success, the integer returned will be a positive integer unique to this request. The request will be considered complete when hyperclient_loop() returns the same ID. If the integer returned is negative, it indicates an error generating the request, and *status contains the reason why. HYPERCLIENT_UNKNOWNATTR, HYPERCLIENT_WRONGTYPE and HYPERCLIENT_DUPEATTR indicate which attribute caused the error by returning -1 - idx_of_bad_attr.

client:
An initialized hyperclient instance.
space:
A NULL-terminated C-string containing the name of the space to retrieve the object from.
key:
A sequence of bytes to be used as the key. This pointer must remain valid for the duration of the call.
key_sz:
The number of bytes pointed to by key.
attrs:
The set of attributes to be changed. Each struct will indicate a map on which to operate with hyperclient_attribute.attr and the key within that map with hyperclient_attribute.map_key. The hyperclient_attribute.value field will be used to atomically modify the specified attribute, thus allowing several attributes to be changed in different ways. This pointer must remain valid for the duration of the call.
attrs_sz:
The number of attributes pointed to by attrs.
status:
A return value in which the result of the operation will be stored. If this function returns successfully, this pointer must remain valid until hyperclient_loop() returns the same ID returned by this function.

The C++ API provides hyperclient::map_atomic_mod in place of this call.

int64_t hyperclient_map_atomic_and(struct hyperclient* client, const char* space, const char* key, size_t key_sz, const struct hyperclient_map_attribute* attrs, size_t attrs_sz, enum hyperclient_returncode* status)

An atomic_and request stores the bitwise-and of the amount specified with the value of each attribute specified by the request. The attributes will be modified atomically without interference from other operations.

Consistency:

atomic_and requests to the same key will be observed in the same order by all clients. All get requests which execute after a given atomic_and request completes will see the results of that atomic_and, or of a later operation which superseded it.

This operation is totally ordered with respect to all get, put, cond_put, delete and other atomic operations.

Efficiency:
The dominating cost of an atomic_and is the same as a put.

On success, the integer returned will be a positive integer unique to this request. The request will be considered complete when hyperclient_loop() returns the same ID. If the integer returned is negative, it indicates an error generating the request, and *status contains the reason why. HYPERCLIENT_UNKNOWNATTR, HYPERCLIENT_WRONGTYPE and HYPERCLIENT_DUPEATTR indicate which attribute caused the error by returning -1 - idx_of_bad_attr.

client:
An initialized hyperclient instance.
space:
A NULL-terminated C-string containing the name of the space to retrieve the object from.
key:
A sequence of bytes to be used as the key. This pointer must remain valid for the duration of the call.
key_sz:
The number of bytes pointed to by key.
attrs:
The set of attributes to be changed. Each struct will indicate a map on which to operate with hyperclient_attribute.attr and the key within that map with hyperclient_attribute.map_key. The hyperclient_attribute.value field will be used to atomically modify the specified attribute, thus allowing several attributes to be changed in different ways. This pointer must remain valid for the duration of the call.
attrs_sz:
The number of attributes pointed to by attrs.
status:
A return value in which the result of the operation will be stored. If this function returns successfully, this pointer must remain valid until hyperclient_loop() returns the same ID returned by this function.

The C++ API provides hyperclient::map_atomic_and in place of this call.

int64_t hyperclient_map_atomic_or(struct hyperclient* client, const char* space, const char* key, size_t key_sz, const struct hyperclient_map_attribute* attrs, size_t attrs_sz, enum hyperclient_returncode* status)

An atomic_or request stores the bitwise-or of the amount specified with the value of each attribute specified by the request. The attributes will be modified atomically without interference from other operations.

Consistency:

atomic_or requests to the same key will be observed in the same order by all clients. All get requests which execute after a given atomic_or request completes will see the results of that atomic_or, or of a later operation which superseded it.

This operation is totally ordered with respect to all get, put, cond_put, delete and other atomic operations.

Efficiency:
The dominating cost of an atomic_or is the same as a put.

On success, the integer returned will be a positive integer unique to this request. The request will be considered complete when hyperclient_loop() returns the same ID. If the integer returned is negative, it indicates an error generating the request, and *status contains the reason why. HYPERCLIENT_UNKNOWNATTR, HYPERCLIENT_WRONGTYPE and HYPERCLIENT_DUPEATTR indicate which attribute caused the error by returning -1 - idx_of_bad_attr.

client:
An initialized hyperclient instance.
space:
A NULL-terminated C-string containing the name of the space to retrieve the object from.
key:
A sequence of bytes to be used as the key. This pointer must remain valid for the duration of the call.
key_sz:
The number of bytes pointed to by key.
attrs:
The set of attributes to be changed. Each struct will indicate a map on which to operate with hyperclient_attribute.attr and the key within that map with hyperclient_attribute.map_key. The hyperclient_attribute.value field will be used to atomically modify the specified attribute, thus allowing several attributes to be changed in different ways. This pointer must remain valid for the duration of the call.
attrs_sz:
The number of attributes pointed to by attrs.
status:
A return value in which the result of the operation will be stored. If this function returns successfully, this pointer must remain valid until hyperclient_loop() returns the same ID returned by this function.

The C++ API provides hyperclient::map_atomic_or in place of this call.

int64_t hyperclient_map_atomic_xor(struct hyperclient* client, const char* space, const char* key, size_t key_sz, const struct hyperclient_map_attribute* attrs, size_t attrs_sz, enum hyperclient_returncode* status)

An atomic_xor request stores the bitwise-xor of the amount specified with the value of each attribute specified by the request. The attributes will be modified atomically without interference from other operations.

Consistency:

atomic_xor requests to the same key will be observed in the same order by all clients. All get requests which execute after a given atomic_xor request completes will see the results of that atomic_xor, or of a later operation which superseded it.

This operation is totally ordered with respect to all get, put, cond_put, delete and other atomic operations.

Efficiency:
The dominating cost of an atomic_xor is the same as a put.

On success, the integer returned will be a positive integer unique to this request. The request will be considered complete when hyperclient_loop() returns the same ID. If the integer returned is negative, it indicates an error generating the request, and *status contains the reason why. HYPERCLIENT_UNKNOWNATTR, HYPERCLIENT_WRONGTYPE and HYPERCLIENT_DUPEATTR indicate which attribute caused the error by returning -1 - idx_of_bad_attr.

client:
An initialized hyperclient instance.
space:
A NULL-terminated C-string containing the name of the space to retrieve the object from.
key:
A sequence of bytes to be used as the key. This pointer must remain valid for the duration of the call.
key_sz:
The number of bytes pointed to by key.
attrs:
The set of attributes to be changed. Each struct will indicate a map on which to operate with hyperclient_attribute.attr and the key within that map with hyperclient_attribute.map_key. The hyperclient_attribute.value field will be used to atomically modify the specified attribute, thus allowing several attributes to be changed in different ways. This pointer must remain valid for the duration of the call.
attrs_sz:
The number of attributes pointed to by attrs.
status:
A return value in which the result of the operation will be stored. If this function returns successfully, this pointer must remain valid until hyperclient_loop() returns the same ID returned by this function.

The C++ API provides hyperclient::map_atomic_xor in place of this call.

int64_t hyperclient_map_string_prepend(struct hyperclient* client, const char* space, const char* key, size_t key_sz, const struct hyperclient_map_attribute* attrs, size_t attrs_sz, enum hyperclient_returncode* status)

A string_prepend request prepends the specified string to the value of each attribute specified by the request. The attributes will be modified atomically without interference from other operations.

Consistency:

string_prepend requests to the same key will be observed in the same order by all clients. All get requests which execute after a given string_prepend request completes will see the results of that string_prepend, or of a later operation which superseded it.

This operation is totally ordered with respect to all get, put, cond_put, delete and other atomic operations.

Efficiency:
The dominating cost of an string_prepend is the same as a put.

On success, the integer returned will be a positive integer unique to this request. The request will be considered complete when hyperclient_loop() returns the same ID. If the integer returned is negative, it indicates an error generating the request, and *status contains the reason why. HYPERCLIENT_UNKNOWNATTR, HYPERCLIENT_WRONGTYPE and HYPERCLIENT_DUPEATTR indicate which attribute caused the error by returning -1 - idx_of_bad_attr.

client:
An initialized hyperclient instance.
space:
A NULL-terminated C-string containing the name of the space to retrieve the object from.
key:
A sequence of bytes to be used as the key. This pointer must remain valid for the duration of the call.
key_sz:
The number of bytes pointed to by key.
attrs:
The set of attributes to be changed. Each struct will indicate a map on which to operate with hyperclient_attribute.attr and the key within that map with hyperclient_attribute.map_key. The hyperclient_attribute.value field will be used to atomically modify the specified attribute, thus allowing several attributes to be changed in different ways. This pointer must remain valid for the duration of the call.
attrs_sz:
The number of attributes pointed to by attrs.
status:
A return value in which the result of the operation will be stored. If this function returns successfully, this pointer must remain valid until hyperclient_loop() returns the same ID returned by this function.

The C++ API provides hyperclient::map_string_prepend in place of this call.

int64_t hyperclient_map_string_append(struct hyperclient* client, const char* space, const char* key, size_t key_sz, const struct hyperclient_map_attribute* attrs, size_t attrs_sz, enum hyperclient_returncode* status)

A string_append request appends the specified string to the value of each attribute specified by the request. The attributes will be modified atomically without interference from other operations.

Consistency:

string_append requests to the same key will be observed in the same order by all clients. All get requests which execute after a given string_append request completes will see the results of that string_append, or of a later operation which superseded it.

This operation is totally ordered with respect to all get, put, cond_put, delete and other atomic operations.

Efficiency:
The dominating cost of an string_append is the same as a put.

On success, the integer returned will be a positive integer unique to this request. The request will be considered complete when hyperclient_loop() returns the same ID. If the integer returned is negative, it indicates an error generating the request, and *status contains the reason why. HYPERCLIENT_UNKNOWNATTR, HYPERCLIENT_WRONGTYPE and HYPERCLIENT_DUPEATTR indicate which attribute caused the error by returning -1 - idx_of_bad_attr.

client:
An initialized hyperclient instance.
space:
A NULL-terminated C-string containing the name of the space to retrieve the object from.
key:
A sequence of bytes to be used as the key. This pointer must remain valid for the duration of the call.
key_sz:
The number of bytes pointed to by key.
attrs:
The set of attributes to be changed. Each struct will indicate a map on which to operate with hyperclient_attribute.attr and the key within that map with hyperclient_attribute.map_key. The hyperclient_attribute.value field will be used to atomically modify the specified attribute, thus allowing several attributes to be changed in different ways. This pointer must remain valid for the duration of the call.
attrs_sz:
The number of attributes pointed to by attrs.
status:
A return value in which the result of the operation will be stored. If this function returns successfully, this pointer must remain valid until hyperclient_loop() returns the same ID returned by this function.

The C++ API provides hyperclient::map_string_append in place of this call.

A search request retrieves all objects which match the specified predicate. These objects may reside on multiple nodes, and the client transparently handles retrieving them from each node. Multiple errors may be returned from a single search; however, the client library will continue to make progress until all servers finish the search or encounter an error.

Consistency:
search results will see the result of every operation which completes prior to the search, unless there is a concurrent operation which supersedes the prior operation.
Efficiency:
The dominating cost of a search is one network round trip per object. Multiple objects will be retrieved in parallel, so searches should be more efficient than simple object retrieval.

The search must match attributes specified by eq and rn. On success, the integer returned will be a positive integer unique to this request. One object or error is returned on each subsequent invocation of hyperclient_loop() which returns the same ID. When hyperclient_loop() set *status to HYPERCLIENT_SEARCHDONE, the search is complete. If the integer returned is negative, it indicates an error generating the request, and *status contains the reason why. HYPERCLIENT_UNKNOWNATTR, HYPERCLIENT_WRONGTYPE and HYPERCLIENT_DUPEATTR indicate which attribute caused the error by returning -1 - idx_of_bad_attr, where idx_of_bad_attr is an index to into the combined attributes of eq and rn.

client:
An initialized hyperclient instance.
space:
A NULL-terminated C-string containing the name of the space to retrieve the object from.
eq:
The attributes to which must match under a strict equality check. This pointer must remain valid for the duration of the call.
eq_sz:
The number of attributes pointed to by eq.
rn:

The attributes to which must fall within the range specified by hyperclient_range_query.lower and hyperclient_range_query.upper

See also

hyperclient_range_query

rn_sz:
The number of attributes pointed to by rn.
status:
A return value in which the result of the operation will be stored. If this function returns successfully, this pointer must remain valid until hyperclient_loop() returns the same ID returned by this function.
attrs:

A return value in which the object (if any) will be stored. This value will be changed if and only if *status is HYPERCLIENT_SUCCESS. If this function returns successfully, this pointer must remain valid until hyperclient_loop() returns the same ID returned by this function with *status set to HYPERCLIENT_SEARCHDONE. This returned value must be released with a call to hyperclient_destroy_attrs().

This value will be overwritten each time hyperclient_loop() returns, and the value will not be saved. It is up to the caller of this function to either destroy the attributes, or preserve a pointer to them before calling hyperclient_loop() again.

See also

hyperclient_attribute, hyperclient_destroy_attrs()

attrs_sz:
The number of hyperclient_attribute instances returned in attrs. This value will be changed if and only if *status is HYPERCLIENT_SUCCESS. If this function returns successfully, this pointer must remain valid until hyperclient_loop() returns the same ID returned by this function with *status set to HYPERCLIENT_SEARCHDONE.

The C++ API provides hyperclient::search in place of this call.

int64_t hyperclient_loop(struct hyperclient* client, int timeout, enum hyperclient_returncode* status)

The loop call is the core event loop that receives and processes server responses. In the normal case, loop will return exactly one completed operation, or in the case of search, one item matching the search result.

It is imperative that the application periodically call loop in order to prevent unbounded resource consumption. Only in the loop function does the client library perform I/O which will clear the recv socket buffers.

The return value is a 64-bit integer which identifies the outstanding operation that was processed. If an error is encountered or the event loop times out when processing the outstanding operations, the return value will be -1, and *status will be set to indicate the reason why.

client:
An initialized hyperclient instance.
timeout:
The number of milliseconds to wait before giving up on event processing.
status:
A return value in which the result of the operation will be stored. This pointer must remain valid for the duration of the call.

The C++ API provides hyperclient::loop in place of this call.

void hyperclient_destroy_attrs(struct hyperclient_attribute* attrs, size_t attrs_sz)

Free an array of hyperclient_attribute objects returned via the hyperclient API. The returned values are allocated in a custom manner, and it is incorrect to free the memory using any other means.

Thread Safety

The HyperClient API uses no global or per-thread state. All state is enclosed in hyperclient instances. Concurrent access to the same hyperclient instance must be protected by external synchronization. The C++ API requires that all calls to members of hyperclient be protected with external synchronization.

Table Of Contents

Previous topic

Python API

Next topic

<no title>

This Page

Navigation

© Copyright 2012, Robert Escriva, Bernard Wong, and Emin Gün Sirer. Created using Sphinx 1.1.3.