Data serialization

This page explains how to perform data serialization when using the OpenDHT API, to store and retrieve structured data in a robust way from the distributed data store.

Building a dht::Value object

dht::Value is a class representing a value stored on, or retrieved from the DHT. dht::Value is a publicly exposed C++ class including a data payload (the data field), as well as other metadata.

From raw data

If you don't need, or already implement serialization, building a dht::Value object from existing binary data is straightforward using the constructor:

Value(const uint8_t* data_ptr, size_t data_size)

Example use:

std::string the_data {"42 cats"};
dht::Value the_dht_value {(const uint8_t*)the_data.data(), the_data.size()};

From structured data with MsgPack

MessagePack is an efficient binary serialization format, used by OpenDHT internally for serialization as well as an API facility to serialize structured user data. OpenDHT uses msgpack-c, a simple, header-only C++11 implementation of MessagePack.

See this page from an introduction about how msgpack-c handles serialisation.

Any data structure implementing msgpack-c serialization methods can be used directly to build a dht::Value object. For instance:

struct MyClass {
    std::string m_str;
    std::vector<int> m_vec;

    // implements msgpack-c serialization methods
    MSGPACK_DEFINE(m_str, m_vec);
};

MyClass the_data {"precious data", {42, 43, 44}};
dht::Value the_dht_value { the_data };

Serializable msgpack objects can be implicitly converted to dht::Values when using OpenDHT methods:

dht::DhtRunner node;

// `MyClass` instance implicitly converted to `dht::Value`
node.put("data_key", MyClass{"precious data", {42, 43, 44}} );