C++ API Documentation

flock::Client

class Client

RAII wrapper around a flock_client_t handle.

A Client is used to create GroupHandle objects for communicating with Flock providers. It is move-only (non-copyable).

See also

flock_client_init, flock_client_finalize

Public Functions

Client() = default: Default constructor. Creates an invalid (null) client.

inline Client(margo_instance_id mid, ABT_pool pool = ABT_POOL_NULL)

Construct a Client from a Margo instance.

See also

flock_client_init

Parameters

mid – Margo instance.
pool – Argobots pool in which to run operations such as updates. Defaults to ABT_POOL_NULL (uses the Margo instance’s default pool).

Throws

flock::Exception – on failure.

inline Client(const thallium::engine &engine, thallium::pool pool = thallium::pool())

Construct a Client from a Thallium engine.

See also

flock_client_init

Parameters

engine – Thallium engine.
pool – Thallium pool in which to run operations such as updates. Defaults to an invalid pool (uses the engine’s default pool).

Throws

flock::Exception – on failure.

inline ~Client()

Destructor. Finalizes the underlying flock_client_t if valid.

See also

flock_client_finalize

inline Client(Client &&other)

Move constructor. Transfers ownership from another Client.

Parameters: other – Client to move from. Left in a null state after the move.

Client(const Client&) = delete: Copy constructor (deleted). Clients are move-only.

Client &operator=(const Client&) = delete: Copy assignment operator (deleted). Clients are move-only.

inline Client &operator=(Client &&other)

Move assignment operator. Transfers ownership from another Client.

If this Client already holds a valid handle, it is finalized first.

Parameters: other – Client to move from. Left in a null state after the move.
Returns: Reference to this Client.

inline GroupHandle makeGroupHandle(hg_addr_t addr, uint16_t provider_id, uint32_t mode = 0) const

Create a GroupHandle by contacting the group member at the given Mercury address and provider ID.

See also

flock_group_handle_create

Parameters

addr – Mercury address of one of the group members.
provider_id – Provider ID of the member.
mode – Optional mode flags (bitwise OR of FLOCK_MODE_INIT_UPDATE and/or FLOCK_MODE_SUBSCRIBE). Defaults to 0.

Throws

flock::Exception – on failure.

Returns

A GroupHandle for the specified group member.

inline GroupHandle makeGroupHandle(const std::string &addr_str, uint16_t provider_id, uint32_t mode = 0) const

Create a GroupHandle by looking up the given address string and contacting the group member at that address and provider ID.

See also

flock_group_handle_create

Parameters

addr_str – Address string of one of the group members.
provider_id – Provider ID of the member.
mode – Optional mode flags (bitwise OR of FLOCK_MODE_INIT_UPDATE and/or FLOCK_MODE_SUBSCRIBE). Defaults to 0.

Throws

flock::Exception – on failure.

Returns

A GroupHandle for the specified group member.

inline auto handle() const

Return the underlying C flock_client_t handle.

Returns: The underlying flock_client_t handle.

inline operator flock_client_t() const

Implicit conversion to flock_client_t.

Returns: The underlying flock_client_t handle.

inline auto engine() const

Return the Thallium engine associated with this Client.

Returns: The Thallium engine.

flock::Exception

class Exception : public std::exception

Exception class for the C++ Flock API.

Wraps a flock_return_t error code (defined in flock-common.h) into a standard C++ exception. Thrown by the C++ wrappers whenever the underlying C function returns a non-success error code.

Public Functions

inline Exception(flock_return_t code)

Construct an Exception from a Flock error code.

Parameters: code – The flock_return_t error code.

inline const char *what() const noexcept override

Return a human-readable description of the error.

Returns: A null-terminated string describing the error.

inline auto code() const

Return the underlying flock_return_t error code.

Returns: The flock_return_t error code.

flock::GroupHandle

class GroupHandle

RAII wrapper around a flock_group_handle_t, providing access to a remote Flock group.

A GroupHandle maintains a reference-counted handle to a remote group. It can be created from a Client (via Client::makeGroupHandle()), from a group file (via GroupHandle::FromFile()), or from a serialized view (via GroupHandle::FromSerialized()).

GroupHandle is copyable (reference-counted) and movable.

See also

flock_group_handle_create, flock_group_handle_release

Public Functions

GroupHandle() = default: Default constructor. Creates an invalid (null) group handle.

inline GroupHandle(flock_group_handle_t gh, bool copy = true)

Construct a GroupHandle from an existing C group handle.

See also

flock_group_handle_ref_incr

Parameters

gh – The C flock_group_handle_t to wrap.
copy – If true (default), the reference count is incremented. If false, this object takes ownership without incrementing.

Throws

flock::Exception – if incrementing the reference count fails.

inline GroupHandle(flock_client_t client, hg_addr_t addr, uint16_t provider_id, bool check = true)

Construct a GroupHandle by contacting the group member at the given address and provider ID.

See also

flock_group_handle_create

Parameters

client – A valid flock_client_t handle.
addr – Mercury address of one of the group members.
provider_id – Provider ID of the member.
check – If true (default), the group member is contacted to verify its existence.

Throws

flock::Exception – on failure.

inline GroupHandle(const GroupHandle &other)

Copy constructor. Increments the reference count of the underlying handle.

Parameters: other – GroupHandle to copy from.
Throws: flock::Exception – if incrementing the reference count fails.

inline GroupHandle(GroupHandle &&other)

Move constructor. Transfers ownership without changing the reference count.

Parameters: other – GroupHandle to move from. Left in a null state after the move.

inline GroupHandle &operator=(const GroupHandle &other)

Copy assignment operator. Releases the current handle (if any) and increments the reference count of the source handle.

Parameters: other – GroupHandle to copy from.
Throws: flock::Exception – on failure.
Returns: Reference to this GroupHandle.

inline GroupHandle &operator=(GroupHandle &&other)

Move assignment operator. Releases the current handle (if any) and transfers ownership from the source.

Parameters: other – GroupHandle to move from. Left in a null state after the move.
Throws: flock::Exception – on failure.
Returns: Reference to this GroupHandle.

inline ~GroupHandle()

Destructor. Releases the underlying group handle, decrementing its reference count.

See also

flock_group_handle_release

inline GroupView view() const

Return a copy of the group’s current view.

See also

flock_group_get_view

Throws: flock::Exception – on failure.
Returns: A GroupView containing a snapshot of the group’s membership and metadata.

inline void update() const

Update the cached internal view of the group by contacting one (or more) of its members. This is a blocking operation.

See also

flock_group_update_view

Throws: flock::Exception – on failure.

inline auto handle() const

Return the underlying C flock_group_handle_t handle.

Returns: The underlying flock_group_handle_t handle.

inline operator flock_group_handle_t() const

Implicit conversion to flock_group_handle_t.

Returns: The underlying flock_group_handle_t handle.

Public Static Functions

static inline GroupHandle FromFile(flock_client_t client, const char *filename, uint32_t mode = 0)

Create a GroupHandle from a group file.

The file must be a JSON document describing the group members and metadata. See flock_group_handle_create_from_file() for the expected format.

See also

flock_group_handle_create_from_file

Parameters

client – A valid flock_client_t handle.
filename – Path to the group file.
mode – Optional mode flags (bitwise OR of FLOCK_MODE_INIT_UPDATE and/or FLOCK_MODE_SUBSCRIBE). Defaults to 0.

Throws

flock::Exception – on failure.

Returns

A GroupHandle for the group described in the file.

static inline GroupHandle FromSerialized(flock_client_t client, std::string_view serialized_view, uint32_t mode = 0)

Create a GroupHandle from a serialized group view.

The serialized data must have been produced by serializing a GroupView (e.g. via its std::string conversion operator) or by flock_group_view_serialize().

See also

flock_group_handle_create_from_serialized

Parameters

client – A valid flock_client_t handle.
serialized_view – A string_view containing the serialized group view data.
mode – Optional mode flags (bitwise OR of FLOCK_MODE_INIT_UPDATE and/or FLOCK_MODE_SUBSCRIBE). Defaults to 0.

Throws

flock::Exception – on failure.

Returns

A GroupHandle for the deserialized group.

flock::GroupView

class GroupView

C++ wrapper around flock_group_view_t, representing a group’s membership and metadata.

A GroupView contains a sorted list of members (address + provider_id pairs) and a sorted map of metadata (key-value string pairs). It maintains a digest (hash) that is automatically updated when members or metadata are added or removed, enabling efficient change detection.

GroupView is move-only (non-copyable via assignment/construction); use copy() to create an explicit deep copy. Access members and metadata through the proxy objects returned by members() and metadata().

The view is thread-safe when accessed via lock()/unlock().

See also

flock_group_view_t

Public Functions

GroupView() = default: Default constructor. Creates an empty group view.

inline GroupView(flock_group_view_t view)

Construct a GroupView by moving from a C flock_group_view_t.

The source view is left empty after the move.

Parameters: view – C group view to move from.

inline ~GroupView()

Destructor. Clears and frees all members and metadata.

See also

flock_group_view_clear

inline GroupView(GroupView &&other)

Move constructor. Transfers ownership of the view’s content.

Parameters: other – GroupView to move from. Left empty after the move.

inline GroupView &operator=(GroupView &&other)

Move assignment operator. Clears the current content and transfers ownership from the source.

Parameters: other – GroupView to move from. Left empty after the move.
Returns: Reference to this GroupView.

inline auto digest() const

Return the digest (hash) of the group view’s content.

The digest is automatically maintained as members and metadata are added or removed. It can be used to efficiently detect whether two views have the same content.

Returns: The digest as a uint64_t.

inline void lock()

Lock the view’s internal mutex for thread-safe access.

See also

FLOCK_GROUP_VIEW_LOCK

inline void unlock()

Unlock the view’s internal mutex.

See also

FLOCK_GROUP_VIEW_UNLOCK

inline void clear()

Clear all members and metadata from the view, resetting the digest to 0.

See also

flock_group_view_clear

inline auto members()

Return a proxy object for accessing and modifying the group’s members.

Returns: A MembersProxy bound to this GroupView.

inline auto metadata()

Return a proxy object for accessing and modifying the group’s metadata.

Returns: A MetadataProxy bound to this GroupView.

inline auto copy() const

Create a deep copy of this GroupView.

All members and metadata are copied into a new GroupView.

Returns: A new GroupView with the same content.

inline operator std::string() const

Serialize the group view to a JSON string.

See also

flock_group_view_serialize

Throws: flock::Exception – on serialization failure.
Returns: A std::string containing the JSON-serialized group view.

struct Member

Represents a group member with an address and provider ID.

Public Members

std::string address: Mercury address of the member.

uint16_t provider_id: Provider ID of the member.

struct MembersProxy

Proxy object for accessing and modifying the members of a GroupView.

Obtained via GroupView::members(). Provides methods to add, remove, find, and index members. All modifications automatically update the view’s digest.

Public Functions

inline void add(const char *address, uint16_t provider_id)

Add a member to the group view.

The member is inserted in sorted order. The caller is responsible for ensuring the (address, provider_id) pair is not already present.

See also

flock_group_view_add_member

Parameters

address – Mercury address of the new member.
provider_id – Provider ID of the new member.

inline void remove(size_t index)

Remove a member by index.

See also

flock_group_view_remove_member

Parameters: index – Zero-based index of the member to remove.
Throws: flock::Exception – with FLOCK_ERR_NO_MEMBER if the index is invalid.

inline void remove(const char *address, uint16_t provider_id)

Remove a member by address and provider ID.

See also

flock_group_view_find_member, flock_group_view_remove_member

Parameters

address – Mercury address of the member to remove.
provider_id – Provider ID of the member to remove.

Throws

flock::Exception – with FLOCK_ERR_NO_MEMBER if the member is not found.

inline bool exists(const char *address, uint16_t provider_id) const

Check whether a member with the given address and provider ID exists.

See also

flock_group_view_find_member

Parameters

address – Mercury address to look up.
provider_id – Provider ID to look up.

Returns

true if the member exists, false otherwise.

inline size_t count() const

Return the number of members in the group view.

See also

flock_group_view_member_count

Returns: The number of members.

inline Member operator[](size_t i) const

Access a member by index.

See also

flock_group_view_member_at

Parameters: i – Zero-based index of the member.
Throws: std::out_of_range – if the index is out of bounds.
Returns: A Member struct containing the address and provider ID.

struct Metadata

Represents a metadata entry as a key-value string pair.

Public Members

std::string key: Metadata key.

std::string value: Metadata value.

struct MetadataProxy

Proxy object for accessing and modifying the metadata of a GroupView.

Obtained via GroupView::metadata(). Provides methods to add, remove, and look up metadata entries. All modifications automatically update the view’s digest.

Public Functions

inline void add(const char *key, const char *value)

Add or update a metadata key-value pair.

If the key already exists, its value is replaced.

See also

flock_group_view_add_metadata

Parameters

key – Metadata key.
value – Metadata value.

inline void remove(const char *key)

Remove a metadata entry by key.

See also

flock_group_view_remove_metadata

Parameters: key – Key of the metadata entry to remove.

inline size_t count() const

Return the number of metadata entries in the group view.

See also

flock_group_view_metadata_count

Returns: The number of metadata entries.

inline Metadata operator[](size_t i) const

Access a metadata entry by index.

See also

flock_group_view_metadata_at

Parameters: i – Zero-based index of the metadata entry.
Throws: std::out_of_range – if the index is out of bounds.
Returns: A Metadata struct containing the key and value.

inline const char *operator[](const char *key) const

Look up a metadata value by key.

See also

flock_group_view_find_metadata

Parameters: key – Key to search for.
Returns: Pointer to the value string, or NULL if the key is not found.

flock::Observer

class Observer

Abstract interface for observing group membership and metadata changes.

Subclass this and override onMembershipUpdate() and onMetadataUpdate() to receive notifications when the group’s state changes. Register an observer with Provider::addObserver() and unregister it with Provider::removeObserver().

Observers are non-copyable and non-movable.

See also

flock_membership_update_fn, flock_metadata_update_fn

Public Functions

Observer(const Observer&) = delete: Copy constructor (deleted). Observers are non-copyable.

Observer(Observer&&) = delete: Move constructor (deleted). Observers are non-movable.

virtual ~Observer() = default: Virtual destructor.

virtual void onMembershipUpdate(flock_update_t update, const char *address, uint16_t provider_id) = 0

Called when a group membership change occurs.

Parameters

update – The type of update (FLOCK_MEMBER_JOINED, FLOCK_MEMBER_LEFT, FLOCK_MEMBER_DIED, or FLOCK_MEMBER_MOVED).
address – Address of the member affected by the update.
provider_id – Provider ID of the member affected by the update.

virtual void onMetadataUpdate(const char *key, const char *value) = 0

Called when a group metadata key/value pair is updated.

Parameters

key – Metadata key that was updated.
value – New value for the metadata key.

flock::Provider

class Provider

RAII wrapper around a flock_provider_t handle.

A Provider registers a Flock group management service with a Margo instance, managing group state via a pluggable backend. It is move-only (non-copyable).

The Provider also registers a Margo finalize callback so that if the Margo instance is finalized before the Provider is destroyed, the internal handle is safely invalidated.

See also

flock_provider_register, flock_provider_destroy

Public Functions

Provider() = default: Default constructor. Creates an invalid (null) provider.

inline Provider(margo_instance_id mid, uint16_t provider_id, const char *config, GroupView &initial_view, ABT_pool pool = ABT_POOL_NULL)

Construct a Provider from a Margo instance.

The config string must be a JSON document specifying the bootstrap method, backend type, and optional backend configuration. See flock_provider_register() for the full configuration format.

See also

flock_provider_register

Parameters

mid – Margo instance.
provider_id – Unique provider ID for this provider within the Margo instance.
config – JSON configuration string.
initial_view – Initial group view. The provider takes ownership of the view’s content and resets it to empty for the caller.
pool – Argobots pool in which to run the provider’s RPCs. Defaults to ABT_POOL_NULL (uses the Margo instance’s default pool).

Throws

flock::Exception – on failure.

inline Provider(const thallium::engine &engine, uint16_t provider_id, const char *config, GroupView &initial_view, const thallium::pool &pool = thallium::pool())

Construct a Provider from a Thallium engine.

Delegates to the Margo-based constructor.

See also

flock_provider_register

Parameters

engine – Thallium engine.
provider_id – Unique provider ID for this provider within the engine.
config – JSON configuration string.
initial_view – Initial group view. The provider takes ownership of the view’s content and resets it to empty for the caller.
pool – Thallium pool in which to run the provider’s RPCs. Defaults to an invalid pool (uses the engine’s default pool).

Throws

flock::Exception – on failure.

inline ~Provider()

Destructor. Destroys the underlying provider and deregisters its RPCs.

See also

flock_provider_destroy

inline Provider(Provider &&other)

Move constructor. Transfers ownership from another Provider.

Parameters: other – Provider to move from. Left in a null state after the move.

Provider(const Provider&) = delete: Copy constructor (deleted). Providers are move-only.

Provider &operator=(const Provider&) = delete: Copy assignment operator (deleted). Providers are move-only.

inline Provider &operator=(Provider &&other)

Move assignment operator. Transfers ownership from another Provider.

If this Provider already holds a valid handle, it is destroyed first.

Parameters: other – Provider to move from. Left in a null state after the move.
Returns: Reference to this Provider.

inline void addObserver(Observer *observer)

Register an Observer to be notified of membership and metadata changes.

The observer pointer is used as the unique context for the callback registration and can be passed to removeObserver() to unregister. Multiple observers may be registered simultaneously with distinct pointers.

See also

flock_provider_add_update_callbacks

Parameters: observer – Pointer to an Observer instance. Must remain valid until removed or the provider is destroyed.
Throws: flock::Exception – on failure.

inline void removeObserver(Observer *observer)

Unregister a previously registered Observer.

See also

flock_provider_remove_update_callbacks

Parameters: observer – Pointer to the Observer to remove. Must match a pointer previously passed to addObserver().
Throws: flock::Exception – on failure.

inline std::string config() const

Return the JSON-formatted configuration of this provider.

See also

flock_provider_get_config

Throws: flock::Exception – on failure.
Returns: A string containing the provider’s JSON configuration.

inline auto handle() const

Return the underlying C flock_provider_t handle.

Returns: The underlying flock_provider_t handle.

inline operator flock_provider_t() const

Implicit conversion to flock_provider_t.

Returns: The underlying flock_provider_t handle.