Reverbrain wiki

Site Tools


elliptics:api-example

Elliptics client usage example

It's recommended to use C++ client API for building applications using elliptics. Elliptics packages for Ubuntu are available at Launchpad. Application written with usage of elliptics client API have to be linked with elliptics_cpp library. The library is written in C++11, so usage of this standard is neccessary, it's possible to set is by option “-std=c++11” or “-std=c++0x” for gcc and clang.

Firstly you should connect to elliptics network. Lets suggest that one of the servers is available by address storage.example.com and port 5222. Also let logger to write data to the file “/var/log/elliptics/elliptics.log” then it's enough to write the following code:

#include <elliptics/session.hpp>
 
int main()
{
    namespace ell = ioremap::elliptics;
 
    ell::file_logger logger("/var/log/elliptics/elliptics.log", DNET_LOG_ERROR);
    ell::node node(logger);
 
    node.add_remote("storage.example.org", 5222);

ioremap::elliptics::session is lightweight container for request arguments. Also it's possible to set groups client should send requests to (All servers in elliptics network are separated to several groups, all files are usually duplicated to different groups for better reliability and perfomance). It's not threadsafe so it's usually neccessary to create it for each request but it will be ommited in current example as it uses only synchronous API.

    ell::session session(node);
    std::vector<int> groups = { 1, 2, 3 };
    session.set_groups(groups);

Data read and write

After session configuration it's now possible to send requests to elliptipcs. It's enough to call write_data for writing the data to elliptics storage:

    std::string data = "fault tolerant distributed key/value storage";
 
    session.write_data(ell::key("elliptics"), data).wait();

Make attention that calling of session::write_data returnes not the data received from the server but async_result<write_result_entry> as all requests in elliptics are mane asynchronously. That's why the wait method was called for blocking current thread and waiting the reply from the server. The exception will be thrown in case of the error like network or hardware errors.

As elliptics is realtime network it's possible to read data right after it's written:

    ell::read_result_entry result = session.read_data(ell::key("elliptics"), 0, 0).get_one();
 
    std::cerr << "Elliptics is \"" << result.file().to_string() << "\"" << std::endl;

The reply from server is waited again and the result is stored to result variable.

Secondary indexes

In addition to simple read, write and removing methods elliptics also support secondary indexes. Let's add object “elliptics” to several secondary-indexes, make attention that it's possible to store additional data in addition to each object-index pair.

    std::vector<std::string> indexes = {
       "fast",
       "reliable",
       "distributed"
    };
 
    // Data specific for key-index pair
    std::vector<ell::data_pointer> indexes_data = {
       ell::data_pointer::copy("data specific for 'elliptics' key and 'fast' index"),
       ell::data_pointer::copy("data specific for 'elliptics' key and 'reliable' index"),
       ell::data_pointer::copy("data specific for 'elliptics' key and 'distributed' index")
    };
 
    session.set_indexes(ell::key("elliptics"), indexes, indexes_data).wait();

Right after this it's possible to find all objects which are “fast” and “reliable” at once.

    std::vector<ell::key> keys;
 
    std::vector<std::string> find_indexes = {
        "fast",
        "reliable"
    };
 
    for (auto entry : session.find_all_indexes(find_indexes)) {
        keys.push_back(entry.id);
    }

Note that it's data written at previous step is accessable from entry element by data structure member.

Bulk read

It's possble to read all found objects in one step:

    for (auto entry : session.bulk_read(keys)) {
        std::cerr << "Found fast and reliable storage: " << entry.file().to_string() << std::endl;
    }

It was used another type of synchronous API at this case: bulk_read receives replies from different servers in asynchornous way, so latency may vary strongly. Iterators-based API allows to process entries received from server as they are received. This makes possible to optimize the memory comsumption as already processed elements are not stored somewhere by elliptics.

elliptics/api-example.txt · Last modified: 2013/07/05 16:47 by elessar