Table Of Contents

7.6. C++

7.6.1. Quick Reference

Return Type Name Arguments
api_buffer;
bool api_buffer::operator==() (const api_buffer & other) const;
bool api_buffer::operator!=() (const api_buffer & other) const;
const char * api_buffer::data() (void) const;
qdb_size_t api_buffer::size() (void) const;
api_buffer_ptr;
const_iterator;
bool const_iterator::operator==() (const const_iterator & other) const;
bool const_iterator::operator!=() (const const_iterator & other) const;
bool const_iterator::operator++() (void);
bool const_iterator::operator--() (void);
const value_type & const_iterator::operator*() (void) const;
const value_type * const_iterator::operator->() (void) const;
qdb_error_t const_iterator::last_error() (void) const;
bool const_iterator::valid() (void) const;
void const_iterator::close() (void);
const_reverse_iterator;
bool const_reverse_iterator::operator==() (const const_reverse_iterator & other) const;
bool const_reverse_iterator::operator!=() (const const_reverse_iterator & other) const;
bool const_reverse_iterator::operator++() (void);
bool const_reverse_iterator::operator--() (void);
const value_type & const_reverse_iterator::operator*() (void) const;
const value_type * const_reverse_iterator::operator->() (void) const;
qdb_error_t const_reverse_iterator::last_error() (void) const;
bool const_reverse_iterator::valid() (void) const;
void const_reverse_iterator::close() (void);
handle;
qdb_error_t handle::attach_tag() (const char * alias, const char * tag);
const_iterator handle::begin() (void);
qdb_error_t handle::blob_put() (const char * alias, const char * content, qdb_size_t content_length, qdb_time_t expiry_time);
qdb_error_t handle::blob_update() (const char * alias, const char * content, qdb_size_t content_length, qdb_time_t expiry_time);
qdb_error_t handle::blob_get_noalloc() (const char * alias, char * content, qdb_size_t * content_length);
api_buffer_ptr handle::blob_get() (const char * alias, qdb_error_t & error);
api_buffer_ptr handle::blob_get_and_remove() (const char * alias, qdb_error_t & error);
api_buffer_ptr handle::blob_get_and_update() (const char * alias, const char * update_content, qdb_size_t update_content_length, qdb_time_t expiry_time, qdb_error_t & error);
api_buffer_ptr handle::blob_compare_and_swap() (const char * alias, const char * new_value, qdb_size_t new_value_length, const char * comparand, qdb_size_t comparand_length, qdb_time_t expiry_time, qdb_error_t & error);
qdb_error_t handle::blob_remove_if() (const char * alias, const char * comparand, qdb_size_t comparand_length);
void handle::close() (void);
qdb_error_t handle::connect() (const char * uri);
bool handle::connected() (void) const;
qdb_error_t handle::detach_tag() (const char * alias, const char * tag);
const_iterator handle::end() (void);
qdb_error_t handle::expires_at() (const char * alias, qdb_time_t expiry_time);
qdb_error_t handle::expires_from_now() (const char * alias, qdb_time_t expiry_delta);
qdb_error_t handle::get_expiry_time() (const char * alias, qdb_time_t & expiry_time);
qdb_error_t handle::get_location() (const char * alias, remote_node & location);
std::vector<std::string> handle::get_tagged() (const char * tag, qdb_error_t & error);
std::vector<std::string> handle::get_tags() (const char * alias, qdb_error_t & error);
qdb_error_t handle::get_type() (const char * alias, qdb_entry_type_t * entry_type);
qdb_error_t handle::int_get() (const char * alias, qdb_int_t * number);
qdb_error_t handle::int_put() (const char * alias, qdb_int_t number, qdb_time_t expiry_time);
qdb_error_t handle::int_update() (const char * alias, qdb_int_t number, qdb_time_t expiry_time);
qdb_error_t handle::int_add() (const char * alias, qdb_int_t addend, qdb_int_t * result = NULL);
qdb_error_t handle::has_tag() (const char * alias, const char * tag);
std::string handle::node_config() (const char * uri, qdb_error_t & error);
std::string handle::node_status() (const char * uri, qdb_error_t & error);
std::string handle::node_topology() (const char * uri, qdb_error_t & error);
handle & handle::operator=() (handle && h);
qdb_error_t handle::purge_all() (void);
const_reverse_iterator handle::rbegin() (void);
qdb_error_t handle::remove() (const char * alias);
const_reverse_iterator handle::rend() (void);
qdb_size_t handle::run_batch() (qdb_operation_t * operations, qdb_size_t operation_count);
std::vector<batch_result> handle::run_batch() (const std::vector<batch_request> & requests, qdb_size_t & success_count);
qdb_error_t handle::run_transaction() (qdb_operation_t * operations, qdb_size_t operation_count, qdb_size_t & fail_index);
qdb_error_t handle::set_compression() (qdb_compression_t comp_level);
qdb_error_t handle::set_timeout() (int timeout);
qdb_error_t handle::stop_node() (const char * uri, const char * reason);
qdb_error_t handle::trim_all() (void);
handle_ptr;
std::string make_error_string() (qdb_error_t err);
api_buffer_ptr make_api_buffer_ptr() (qdb_handle_t h, const char * data, qdb_size_t length);

7.6.2. Introduction

The quasardb C++ API is a wrapper around the C API that brings convenience and flexibility without sacrificing performance. Because the behaviour is similar to the C API, you may wish to familiarize yourself with the C API before working with the C++ API (see C).

7.6.3. Installing

The C++ API package is qdb-capi-<version>, and can be downloaded from the Bureau 14 download site. All information regarding the Bureau 14 download site is in your welcome e-mail. The contents of the C++ API package are:

\qdb-capi-<version>
      \doc        // This documentation
      \example    // C and C++ API examples
      \include    // C and C++ header files
      \lib        // QDB API shared libraries

All functions, typedefs and enums are made available in the include/qdb/client.hpp header file. All classes and methods reside in the qdb namespace.

Both the C and C++ header files must be linked into the client executable. No other linking is required.

7.6.4. The handle object

The handle object is non-copiable. Move semantics are supported through rvalue references but must be enabled by setting the QDBAPI_RVALUE_SUPPORT macro to 1. For example:

#define QDBAPI_RVALUE_SUPPORT 1
#include <qdb/client.hpp>

Handle objects can be used directly with the C API thanks to the overload of the cast operator. They will evaluate to false when not initialized:

qdb::handle h;
// some code...
if (!h) // true if h isn't initialized
{
    // ...
}

// initialization and connection

// removes the entry "myalias" if it exists
qdb_error_t r = qdb_remove(h, "myalias");
if (r != qdb_e_ok)
{
    // error management
}

Caution

Calling qdb_close() on a handle leads to undefined behaviour. Generally speaking it is advised to use the handle object’s methods rather than the C API functions. The cast operator is provided for compatibility only.

Handle objects can also be encapsulated in smart pointers. A definition as handle_ptr is available. This requires a compiler with std::shared_ptr support.

7.6.5. The api_buffer object

The api_buffer object is designed to be used via a smart pointer - whose definition is provided - and is returned by methods from the handle object. It is possible to access the managed buffer directly (read-only) and query its size (see api_buffer::data() and api_buffer::size()).

7.6.6. Connecting to a cluster

The connection requires a handle object and is done with the handle::connect() method:

qdb::handle h;
qdb_error_t r = h.connect("qdb://127.0.0.1:2836");

Handle::connect will both initialize the handle and connect to the cluster. If the connection fails, the handle will be reset. Note that when the handle object goes out of scope, the connection will be terminated and the handle will be released.

Caution

Concurrent calls to connect on the same handle object leads to undefined behaviour.

7.6.7. Adding and getting data to and from a cluster

Although you may use the handle object with the C API, using the handle object’s methods is recommended. For example, to put and get an entry, the C++ way:

const char in_data[10];

qdb_error_t r = h.put("entry", in_data, 0);
if (r != qdb_e_ok)
{
    // error management
}

// ...

char out_data[10];
qdb_error_t r = h.get("entry", out_data, 10);
if (r != qdb_e_ok)
{
    // error management
}

The largest difference between the C and C++ get calls are their memory allocation lifetimes. The C call qdb_get() allocates a buffer of the needed size and must be explicitly freed. The C++ handle.get() method uses uses smart pointers to manage allocations lifetime.

In C, you would write:

char * allocated_content = 0;
qdb_size_t allocated_content_length = 0;
r = qdb_get(handle, "entry", &allocated_content, &allocated_content_length);
if (r != qdb_e_ok)
{
    // error management
}

// ...
// later
// ...

qdb_free_buffer(allocated_content);

In C++, you allocate an api_buffer_ptr and it is released when its reference count reaches zero, like a smart pointer:

qdb_error_t r = qdb_e_ok;
qdb::api_buffer_ptr allocated_content = h.get("entry", r);
if (r != qdb_e_ok)
{
    // error management
}

7.6.8. Closing a connection

A connection can be explicitly closed and the handle released with the handle::close() method:

h.close();

Note that when the handle object is destroyed, handle::close() is automatically called.

Caution

The usage of qdb_close() with handle object results in undefined behaviour.

7.6.9. Expiry

Expiry is set with handle::expires_at() and expires_from_now(). It is obtained with handle::get_expiry_time(). Expiry time is always in seconds, either relative to epoch (January 1st, 1970 00:00 UTC) when using handle::expires_at() or relative to the call time when using expires_from_now().

Danger

The behavior of expires_from_now() is undefined if the time zone or the clock of the client computer is improperly configured.

To set the expiry time of an entry to 1 minute, relative to the call time:

char content[100];

// ...

r = h.put("myalias", content, sizeof(content), 0);
if (r != qdb_error_ok)
{
    // error management
}

r = h.expires_from_now("myalias", 60);
if (r != qdb_error_ok)
{
    // error management
}

To prevent an entry from ever expiring:

r = h.expires_at("myalias", 0);
if (r != qdb_error_ok)
{
    // error management
}

By default, entries do not expire. To obtain the expiry time of an existing entry:

qdb_time_t expiry_time = 0;
r = h.get_expiry_time("myalias", &expiry_time);
if (r != qdb_error_ok)
{
    // error management
}

7.6.10. Batch operations

Batch operations are used similarly as in C, except a method handle::run_batch() is provided for convenience.

7.6.11. Iteration

Iteration on the cluster’s entries can be done forward and backward.

An STL-like iterator API is provided which is compatible with STL algorithms:

// forward loop
std::for_each(h.begin(), h.end(), [](const qdb::const_iterator::value_type & v)
{
    // work on the entry
    // v.first is an std::string refering to the entry's alias
    // v.second is qdb::api_buffer_ptr with the entry's content
});

// backward loop
std::for_each(h.rbegin(), h.rend(), [](const qdb::const_reverse_iterator::value_type & v) { /* work on the entry */ });

There is however a significant difference with regular STL iterators: since entries are accessed remotely, an error may prevent the next entry from being retrieved, in which case the iterator will be considered to have reached the “end” of the iteration.

It is however possible to query the last error through the last_error() member function. The qdb_e_alias_not_found indicates the normal end of the iteration whereas other error statuses indicate that the iteration could not successfully complete. It is up to the programmer to decide what to do in case of error.

Iterators’ value is a std::pair<std::string, qdb::api_buffer_ptr> which makes the manipulation of iterator associated data safe in most scenarii. Associated resources will be freed automatically through RAII.

The iterator api may throw the std::bad_alloc exception should a memory allocation fail.

Note

Although each entry is returned only once, the order in which entries are returned is undefined.

7.6.12. Exceptions

The quasardb C++ API does not throw any exception on its behalf, however situations such as low memory conditions may cause exceptions to be thrown.

7.6.13. Reference

Warning

doxygennamespace: Cannot find file: /mnt/resource/TeamCity/work/d5a5dab08ea351ed/apis/cpp/output/xml/index.xml

arrow_backPrevious
7.5. Performance profiling
Next arrow_forward
7.7. Go