Key-Value Store API

This page presents the API that a CCF application must use to access and mutate the replicated key-value store.

A CCF application should store its data in one or more ccf::kv::Map. The name, type, and serialisation of these maps is under the application’s control. Each invocation of an ccf::EndpointRegistry::Endpoint is given a ccf::kv::Tx transaction object, through which it can read and write to its ccf::kv::Map.

Map

typedef uint64_t ccf::kv::Version

static constexpr Version ccf::kv::NoVersion = 0u

template<typename K, typename V, typename KSerialiser, typename VSerialiser>
class TypedMap : public ccf::kv::GetName

Defines the schema of a map accessed by a ccf::Tx, exposing associated types. This map is an unordered associative container of key-value pairs. Each key, if defined, is associated with a value, and can be used to efficiently lookup that value.

K defines the type of the Key which indexes each entry, while V is the type of the Value associated with a given Key. KSerialiser and VSerialiser determine how each K and V are serialised and deserialised, so they may be written to the ledger and replicated by the consensus algorithm. Note that equality is always evaluated on the serialised form; if unequal Ks produce the same serialisation, they will coincide within this map. Serialiser which leverages existing JSON serialisation is provided by CCF.

template<typename K, typename V>
using ccf::kv::Map = JsonSerialisedMap<K, V>

Short name for default-serialised maps, using JSON serialisers. Support for custom types can be added through the DECLARE_JSON… macros.

template<typename V, typename VSerialiser, typename Unit = ccf::kv::serialisers::ZeroBlitUnitCreator>
class TypedValue : public ccf::kv::GetName

Defines the schema of a single-valued type accessed by a ccf::Tx. This value type is a container for an optional single element of type V. This may be undefined if the value has not been written to the KV, or else it has the value from the current or last-applied transaction.

V defines the type of the contained Value. VSerialiser determines how this V is serialised and deserialised, so it may be written to the ledger and replicated by the consensus algorithm.

This is implemented as a ccf::kv::Map from Unit to V, and the serialisation of the unit key is overridable with the Unit template parameter.

template<typename V>
using ccf::kv::Value = JsonSerialisedValue<V>

Short name for default-serialised values, using JSON serialisers. Support for custom types can be added through the DECLARE_JSON… macros.

template<typename K, typename KSerialiser, typename Unit = ccf::kv::serialisers::ZeroBlitUnitCreator>
class TypedSet : public ccf::kv::GetName

Defines the schema of a set type accessed by a ccf::Tx. This set is an unordered container of unique keys. Each key is either present or missing within the set, and key presence can be efficiently tested.

K defines the type of each entry in this set. KSerialiser determines how each K is serialised and deserialised, so they may be written to the ledger and replicated by the consensus algorithm. Note that equality is always evaluated on the serialised form; if unequal Ks produce the same serialisation, they will coincide within this set.

This is implemented as a ccf::kv::Map from K to Unit, and the serialisation of the unit values is overridable with the Unit template parameter.

template<typename K>
using ccf::kv::Set = JsonSerialisedSet<K>

Short name for default-serialised sets, using JSON serialisers. Support for custom types can be added through the DECLARE_JSON… macros.

Transaction

class ReadOnlyTx : public ccf::kv::BaseTx

Used to create read-only handles for accessing a Map.

Acquiring a handle will create the map in the KV if it does not yet exist. The returned handles can view state written by previous transactions, and any additional modifications made in this transaction.

Subclassed by ccf::kv::Tx

Public Functions

template<class M>
inline M::ReadOnlyHandle *ro(M &m)

Get a read-only handle from a map instance.

Parameters:

m – Map instance

template<class M>
inline M::ReadOnlyHandle *ro(const std::string &map_name)

Get a read-only handle by map name. Map type must be specified as explicit template parameter.

Parameters:

map_name – Name of map

class Tx : public ccf::kv::ReadOnlyTx

Used to create writeable handles for accessing a Map.

Acquiring a handle will create the map in the KV if it does not yet exist. Any writes made by the returned handles will be visible to all other handles created by this transaction. They will only be visible to other transactions after this transaction has completed and been applied. For type-safety, prefer restricted handles returned by ro or wo where possible, rather than the general rw.

See also

ccf::kv::ReadOnlyTx

Subclassed by ccf::kv::CommittableTx

Public Functions

template<class M>
inline M::Handle *rw(M &m)

Get a read-write handle from a map instance.

This handle can be used for both reads and writes.

Parameters:

m – Map instance

template<class M>
inline M::Handle *rw(const std::string &map_name)

Get a read-write handle by map name. Map type must be specified as explicit template parameter.

Parameters:

map_name – Name of map

template<class M>
inline M::WriteOnlyHandle *wo(M &m)

Get a write-only handle from a map instance.

Parameters:

m – Map instance

template<class M>
inline M::WriteOnlyHandle *wo(const std::string &map_name)

Get a write-only handle by map name. Map type must be specified as explicit template parameter.

Parameters:

map_name – Name of map

Handles

template<typename K, typename V, typename KSerialiser, typename VSerialiser>
class ReadableMapHandle

Grants read access to a ccf::kv::Map, as part of a ccf::kv::Tx.

Subclassed by ccf::kv::MapHandle< K, V, KSerialiser, VSerialiser >

Public Functions

inline std::string get_name_of_map() const

Get name of this map.

Returns:

String containing name used to construct this map handle

inline std::optional<V> get(const K &key)

Get value for key.

This returns the value for the key as seen by this transaction. If the key has been updated in the current transaction, that update will be reflected in the return of this call. Where the key has not been modified, this returns the state of a snapshot version from the start of the transaction’s execution.

Parameters:

key – Key to read

Returns:

Optional containing associated value, or empty if the key doesn’t exist

inline std::optional<V> get_globally_committed(const K &key)

Get globally committed value for key, which has been replicated and acknowledged by consensus protocol.

This reads a globally replicated value for the specified key. The value will have been the most recent replicated value when the transaction began. Consensus may have advanced and committed a more recent version while this transaction executes. This is undetectable to the transaction.

Parameters:

key – Key to read

Returns:

Optional containing associated value, or empty if the key doesn’t exist in globally committed state

inline