Realm::Runtime::KeyValueStoreVtable Struct Reference

#include <runtime.h>

Public Attributes
const void *	vtable_data
size_t	vtable_data_size
bool(*	put )(const void *key, size_t key_size, const void *value, size_t value_sizem, const void *vtable_data, size_t vtable_data_size) = nullptr
bool(*	get )(const void *key, size_t key_size, void *value, size_t *value_size, const void *vtable_data, size_t vtable_data_size) = nullptr
bool(*	bar )(const void *vtable_data, size_t vtable_data_size) = nullptr
bool(*	cas )(const void *key, size_t key_size, void *expected, size_t *expected_size, const void *desired, size_t desired_size, const void *vtable_data, size_t vtable_data_size) = nullptr

Static Public Attributes
static constexpr std::string_view	group_key = "realm_group"
static constexpr std::string_view	rank_key = "realm_rank"
static constexpr std::string_view	ranks_key = "realm_ranks"

Detailed Description

Some networks prefer to bootstrap via callbacks using a vtable A client provides an implementation of the functions in the vtable and Realm will invoke them as part of bootstrapping the network and providing support for elasticity (when networks support it). Some functions are required while others are either/or options. All callbacks will either be performed in an external thread (one not made by Realm but has called into Realm) or by a designated Realm thread independent of Realm's background worker threads so that clients can use non-Realm synchronization primitives in the implementation of these functions and not need to worry about blocking or impacting forward progress.

Member Data Documentation

bar

bool(* Realm::Runtime::KeyValueStoreVtable::bar) (const void *vtable_data, size_t vtable_data_size) = nullptr

cas

bool(* Realm::Runtime::KeyValueStoreVtable::cas) (const void *key, size_t key_size, void *expected, size_t *expected_size, const void *desired, size_t desired_size, const void *vtable_data, size_t vtable_data_size) = nullptr

The "cas" function should be provided in cases of elastic bootstrap when an arbitrary number of processes can join or leave the Realm during its execution. The cas function should perform an atomic compare-and-swap operation on a key by checking that the key matches a particular value and if it does then updating it with the desired value in a single atomic operation. If the key does not yet exist then the transaction should create the key with the desirecd value. If the value associated with the key does not match the expected result, the call should fail, but return the updated expected value and size as long as it is less than or equal to the original expected size. If the new value size is larger than the expected size, then only the expected_size should be updated. It is possible for this call to fail and for the bootstrap to continue, although a large number of repetitive failures will likely lead to a timeout.

get

bool(* Realm::Runtime::KeyValueStoreVtable::get) (const void *key, size_t key_size, void *value, size_t *value_size, const void *vtable_data, size_t vtable_data_size) = nullptr

The "get" function must retrieve the value associated with the given key if it can be found. Realm will call this function with the value buffer already allocated with the value_size populated with the maximum size of the value that can be returned. If the key is found and the value size is less than or equal to the value_size passed in by Realm, then the value buffer should be populated and the value_size updated with the actual size of the value found. If the key is found but the resulting value is larger than the buffer size, then the function should update value_size with the actual size of the buffer but does not need to populate the value buffer (sinze it obviously will not fit). If the key cannot be found then the value size should be set to zero. The function should always return true as long as the get call works correctly (even if a key is not found or the buffer is not larger enough). Returning false should only occur if the function call fails in some way that makes it impossible to know if the key exists or not. If the callback fails then the network initialization might not succeed.

group_key

constexpr std::string_view Realm::Runtime::KeyValueStoreVtable::group_key = "realm_group"

inlinestaticconstexpr

The "bar" function should be provided in cases where processes are joining and leaving the Realm as a group. It must perform a barrier across all the processes in the (implicit) group that this process is a part of along with flushing any puts done before it. It should return true if the barrier succeeds and false if it fails. If the barrier fails then it can be expected the Realm bootstrap will also fail. If you provide a bar method, then you must also provide support in the "get" method for three special keys:

• "realm_group": the value associated with this key must be interpretable as an integer that is the same for all processes that cooperate in this barrier. It must be distinct from any other group identifier for other processes that are joining the same Realm.
• "realm_ranks": the value associated with this key must be interpretable as an integer that indicates how many processes are participating in this barrier operation together.
• "realm_rank": the value associated with this key must be interpretable as an integer that uniquely identifies this process in its local group. It must be in the range [0, realm_ranks). Note that each group should have its rank numbering start at zero and grow incrementally. Rank numbers are therefore the same across groups. Realm will generate a unique address space for each process as part of the bootstrap.

put

bool(* Realm::Runtime::KeyValueStoreVtable::put) (const void *key, size_t key_size, const void *value, size_t value_sizem, const void *vtable_data, size_t vtable_data_size) = nullptr

The "put" function must store a global key value pair in a way that it can be retrieved from any other process using a corresponding get call. The function is passed a buffer containing a key and buffer containing a value. The implementation must copy these values before returning from the callback if it needs to persist them as they are not guaranteed to live longer than the function call. The function should return true if the put succeeds and false if it doesn't. If the call fails then it is likely that the network initialization might not succeed.

rank_key

constexpr std::string_view Realm::Runtime::KeyValueStoreVtable::rank_key = "realm_rank"

inlinestaticconstexpr

ranks_key

constexpr std::string_view Realm::Runtime::KeyValueStoreVtable::ranks_key = "realm_ranks"

inlinestaticconstexpr

vtable_data

const void* Realm::Runtime::KeyValueStoreVtable::vtable_data

Optional blob of data passed to all the network vtable functions when they are invoked by Realm. Realm will not attempt to interpret this data at all but will simply pass it through to each call. You do not have to pass any data through to implement the callbacks, it is purely for your convenience.

vtable_data_size

size_t Realm::Runtime::KeyValueStoreVtable::vtable_data_size

---

The documentation for this struct was generated from the following file:

• /home/runner/work/realm/realm/realm-src/src/realm/runtime.h