C++ API Documentation

bedrock::AsyncRequest

class AsyncRequest

AsyncRequest objects are used to keep track of on-going asynchronous operations.

Public Functions

AsyncRequest(): Default constructor. Will create a non-valid AsyncRequest.

AsyncRequest(const AsyncRequest &other): Copy constructor.

AsyncRequest(AsyncRequest &&other): Move constructor.

AsyncRequest &operator=(const AsyncRequest &other): Copy-assignment operator.

AsyncRequest &operator=(AsyncRequest &&other): Move-assignment operator.

~AsyncRequest(): Destructor.

void wait() const: Wait for the request to complete.

bool completed() const: Test if the request has completed, without blocking.

bool active() const: Returns whether the AsyncRequest object is associated with a pending operation. If true, the wait() function needs to be invoked before the request can be reused for another call.

operator bool() const: Checks if the object is valid.

bedrock::Client

class Client

The Client object is the main object used to establish a connection with a Bedrock service.

Public Functions

Client(): Default constructor.

Client(margo_instance_id mid)

Constructor using a margo instance id.

Parameters: mid – Margo instance id.

Client(const thallium::engine &engine)

Constructor.

Parameters: engine – Thallium engine.

Client(const Client&): Copy constructor.

Client(Client&&): Move constructor.

Client &operator=(const Client&): Copy-assignment operator.

Client &operator=(Client&&): Move-assignment operator.

~Client(): Destructor.

const thallium::engine &engine() const: Returns the thallium engine used by the client.

ServiceHandle makeServiceHandle(const std::string &address, uint16_t provider_id = 0) const

Creates a handle to a remote Service.

Parameters

address – Address of the provider holding the database.
provider_id – Provider id.

Returns

a ServiceHandle instance.

ServiceGroupHandle makeServiceGroupHandleFromFlockFile(const std::string &groupfile, uint16_t provider_id = 0) const

Creates a handle to a group of Bedrock processes from an Flock group file.

Parameters

groupfile – Flock group file.
provider_id – Provider ID of the bedrock providers.

Returns

ServiceGroupHandle instance.

ServiceGroupHandle makeServiceGroupHandleFromFlockGroup(flock_group_handle_t handle, uint16_t provider_id = 0) const

Creates a handle to a group of Bedrock processes.

Parameters

handle – Existing Flock group handle.
provider_id – Provider ID of the bedrock providers.

Returns

ServiceGroupHandle instance.

ServiceGroupHandle makeServiceGroupHandle(const std::vector<std::string> &addresses, uint16_t provider_id = 0) const

Creates a handle to a group of Bedrock processes from a list of addresses. This type of group cannot be refreshed.

Parameters

addresses – Array of addresses.
provider_id – Provider ID of the bedrock providers.

Returns

ServiceGroupHandle instance.

operator bool() const: Checks that the Client instance is valid.

bedrock::DependencyFinder

class DependencyFinder

A DependencyFinder is an object that takes a dependency specification and resolves it into a void* handle to that dependency.

Public Functions

DependencyFinder(const MPIEnv &mpi, const MargoManager &margo, const ProviderManager &pmanager)

Constructor.

Parameters

mpi – MPI context
margo – Margo context
pmanager – Provider manager

DependencyFinder(const DependencyFinder&): Copy-constructor.

DependencyFinder(DependencyFinder&&): Move-constructor.

DependencyFinder &operator=(const DependencyFinder&): Copy-assignment operator.

DependencyFinder &operator=(DependencyFinder&&): Move-assignment operator.

~DependencyFinder(): Destructor.

operator bool() const: Checks whether the DependencyFinder instance is valid.

std::shared_ptr<NamedDependency> find(const std::string &type, const std::string &spec, std::string *resolved) const

Resolve a specification, returning a void* handle to it. This function throws an exception if the specification could not be resolved. A specification is either a name, or a string follows the following grammar:

SPEC := IDENTIFIER | IDENTIFIER ‘@’ LOCATION IDENTIFIER := SPECIFIER | NAME ‘->’ SPECIFIER SPECIFIER := NAME | TYPE ‘:’ ID LOCATION := ADDRESS ADDRESS := <mercury address> NAME := <qualified identifier> ID := <provider id>

For instance, “abc” represents the name “abc”. “abc:123” represents a provider of type “abc” with provider id 123. “abc@address” represents a provider handle pointing to a provider named “abc” at address “address”.

Parameters

type – [in] Type of dependency.
spec – [in] Specification string.
Resolved – [out] specification.

Returns

handle to dependency

std::shared_ptr<NamedDependency> find(const std::string &type, size_t index, std::string *resolved) const

Find a dependency by an “index” value. The dependency should be a pool or an xstream.

Parameters

type – [in] Type of dependency.
index – [in] Index of the dependency.
resolved – [out] Resolved specification.

Returns

handle to dependency

std::shared_ptr<NamedDependency> findProvider(const std::string &type, uint16_t provider_id) const

Find a local provider based on a type and provider id. Throws an exception if not found.

Parameters

type – Provider type
provider_id – Provider id

Returns

An abstract pointer to the dependency.

std::shared_ptr<NamedDependency> findProvider(const std::string &type, const std::string &name, uint16_t *provider_id = nullptr) const

Find a local provider based on a name. Throws an exception if not found.

Parameters

type – [in] Type of provider
name – [in] Provider name
provider_id – [out] Provider id found

Returns

An abstract pointer to the dependency.

std::shared_ptr<NamedDependency> makeProviderHandle(const std::string &type, uint16_t provider_id, const std::string &locator, std::string *resolved) const

Make a provider handle to a specified provider. Throws an exception if no provider was found with this provider id at the specified location.

Parameters

type – Type of service.
provider_id – Provider id
locator – Location (e.g. “local” or mercury address)
resolved – Output resolved specification

Returns

An abstract pointer to the dependency.

std::shared_ptr<NamedDependency> makeProviderHandle(const std::string &type, const std::string &name, const std::string &locator, std::string *resolved) const

Make a provider handle to a specified provider. Throws an exception if no provider was found with this provider name at the specified location.

Parameters

type – Type of service.
name – Name of the provider
locator – Location (e.g. “local” or mercury addresses)
resolved – Output resolved specification

Returns

An abstract pointer to the dependency.

bedrock::Jx9Manager

class Jx9Manager

The Jx9Manager class encapsulates a Jx9 engine.

Public Functions

Jx9Manager(MPIEnv mpiEnv): Constructor.

Jx9Manager(const Jx9Manager&): Copy-constructor.

Jx9Manager(Jx9Manager&&): Move-constructor.

Jx9Manager &operator=(const Jx9Manager&): Copy-assignment operator.

Jx9Manager &operator=(Jx9Manager&&): Move-assignment operator.

~Jx9Manager(): Destructor.

operator bool() const: Checks whether the Jx9Manager instance is valid.

void setVariable(const std::string &name, const std::string &value)

Install a global variable that will be made available whenever a query is made.

Parameters

name – Name of the variable.
value – Value (JSON formatted string).

void unsetVariable(const std::string &name): Unset a global variable.

std::string executeQuery(const std::string &script, const std::unordered_map<std::string, std::string> &variables) const

This function executes the provided script and returns the content of value returned by the script.

In case of a Jx9 error, this function will throw an Exception.

Parameters

script – Content of the script to execute.
variables – variables to add to the jx9 VM.

Returns

The serialized returned value of the script.

bool evaluateCondition(const std::string &condition, const std::unordered_map<std::string, std::string> &variables) const: Evaluate a condition written in Jx9.

bedrock::MPIEnv

class MPIEnv

Public Functions

~MPIEnv(): The last call to the destructor will finalize MPI if it has been initialized by Bedrock.

bool isEnabled() const

Returns true if Bedrock was built with MPI support. If it hasn’t, all the methods bellow will throw an Exception.

Parameters: engine – Thallium engine.

int globalSize() const: Return the size of MPI_COMM_WORLD.

int globalRank() const: Return the rank of the current process in MPI_COMM_WORLD.

const std::string &addressOfRank(int rank) const

Return the Mercury address of the given rank.

Parameters: rank – Rank of the process.

bedrock::MargoManager

class MargoManager

The MargoManager class is encapsulates a margo_instance_id.

Public Functions

MargoManager(const std::vector<std::string> &addresses, const std::vector<std::string> &configs)

Constructor for multiple engines.

Parameters

addresses – Vector of addresses (one per engine).
configs – Vector of JSON configuration strings (one per engine).

inline MargoManager(const std::string &address, const std::string &configString = "")

Constructor from a JSON configurations string.

Parameters

address – Address.
configString – Configuration string.

MargoManager(const MargoManager&): Copy-constructor.

MargoManager(MargoManager&&): Move-constructor.

MargoManager &operator=(const MargoManager&): Copy-assignment operator.

MargoManager &operator=(MargoManager&&): Move-assignment operator.

~MargoManager(): Destructor.

operator bool() const: Checks whether the MargoManager instance is valid.

size_t getNumEngines() const: Get the number of engines.

margo_instance_id getMargoInstance(size_t engineIndex = 0) const: Get the internal margo_instance_id for a specific engine.

const tl::engine &getThalliumEngine(size_t engineIndex = 0) const: Get a specific thallium engine.

std::shared_ptr<NamedDependency> getDefaultHandlerPool(size_t engineIndex = 0) const: Get the default handle pool from a specific engine.

std::shared_ptr<NamedDependency> getPool(const std::string &name) const: Get the pool corresponding to a particular name.

std::shared_ptr<NamedDependency> getPool(uint32_t index) const: Get the pool corresponding to a particular index.

std::shared_ptr<NamedDependency> getPool(ABT_pool pool) const: Get the pool corresponding to a particular handle.

size_t getNumPools() const: Get the number of pools.

std::shared_ptr<NamedDependency> addPool(const std::string &config): Add a pool from a JSON configuration, returning the corresponding PoolInfo object.

void removePool(const std::string &name): Remove a pool by its name.

void removePool(uint32_t index): Remove a pool by its index.

void removePool(ABT_pool pool): Remove a pool by its handle.

std::shared_ptr<NamedDependency> getXstream(const std::string &name) const: Get the xstream corresponding to a particular name.

std::shared_ptr<NamedDependency> getXstream(uint32_t index) const: Get the xstream corresponding to a particular index.

std::shared_ptr<NamedDependency> getXstream(ABT_xstream es) const: Get the xstream corresponding to a particular handle.

size_t getNumXstreams() const: Get the number of pools.

std::shared_ptr<NamedDependency> addXstream(const std::string &config): Add an ES from a JSON configuration, returning the corresponding XstreamInfo object.

void removeXstream(uint32_t index): Remove an ES by its index.

void removeXstream(const std::string &name): Remove an xstream by its name.

void removeXstream(ABT_xstream xstream): Remove an xstream by its handle.

std::string getCurrentConfig() const: Return the current JSON configuration.

bedrock::ProviderDescriptor

Warning

doxygenclass: Cannot find class “bedrock::ProviderDescriptor” in doxygen xml output for project “bedrock” from directory: /home/docs/checkouts/readthedocs.org/user_builds/mochi/checkouts/latest/docs/source/bedrock/doxygen

bedrock::ProviderManager

class ProviderManager

A ProviderManager is a Bedrock provider that manages a list of providers and uses the ModuleContext to create new ones from configuration files.

Public Functions

ProviderManager(const MargoManager &margo, const Jx9Manager &jx9, uint16_t provider_id, std::shared_ptr<NamedDependency> pool)

Constructor.

Parameters

margo – Margo context
jx9 – Jx9Manager
provider_id – Provider id at which this provider manager
pool – Pool in which to execute RPCs looking up providers

ProviderManager(const ProviderManager&): Copy-constructor.

ProviderManager(ProviderManager&&): Move-constructor.

ProviderManager &operator=(const ProviderManager&): Copy-assignment operator.

ProviderManager &operator=(ProviderManager&&): Move-assignment operator.

~ProviderManager(): Destructor.

operator bool() const: Checks whether the ProviderManager instance is valid.

void setDependencyFinder(const DependencyFinder &finder)

Set the DependencyFinder object to use to resolve dependencies.

Parameters: finder – DependencyFinder

size_t numProviders() const: Return the number of providers registered.

std::shared_ptr<ProviderDependency> getProvider(const std::string &name) const

Get an internal provider instance by its name. If not found, this function will throw an Exception. If returned, the shared_ptr is guaranteed not to be null.

Note: contrary to lookupProvider, which can accept either “name” or “type:id” as specification, getProvider only expects a provider’s name as argument.

Returns: a NamedDependency representing the provider instance.

std::shared_ptr<ProviderDependency> getProvider(size_t index) const

Get an internal provider instance by its index. If not found, this function will throw an Exception. If returned, the shared_ptr is guaranteed not to be null.

Returns: a NamedDependency representing the provider instance.

std::shared_ptr<ProviderDependency> lookupProvider(const std::string &spec) const

Look up whether a provider with a given specification exists. The specification must be in the form “<provider-name>” (e.g. “myprovider”) or “<provider-type>:<provider-id>” (e.g. “bake:42”). This function returns true if a provider satisfying the spec was found, false otherwise. If a provider is found and wrapper is not nullptr, wrapper is set to the corresponding ProviderWrapper.

Parameters: spec – [in] Specification string
Returns: a std::shared_ptr<ProviderDependency> pointing to the provider dependency, this pointer will be null if no provider was found.

void deregisterProvider(const std::string &spec)

Deregister a provider from a specification. The specification has the same format as in lookupProvider().

Parameters: spec – Specification string

std::shared_ptr<ProviderDependency> addProviderFromJSON(const json &description)

Add a provider from a JSON description. The description should be of the following form:

{ “type” : “remi”, “name” : “my_remi_provider”, “provider_id” : 23, “dependencies” : { “abt_io” : “my_abt_io” }, “config” : { … }, “tags”: [ “tags1”, “tag2”, … ] }

Parameters: jsonString – JSON string.

void addProviderListFromJSON(const json &list)

Add a list of providers represented by a JSON array.

Parameters: list – JSON array.

void migrateProvider(const std::string &provider, const std::string &dest_addr, uint16_t dest_provider_id, const std::string &migration_config, bool remove_source)

Migrates the specified provider state to the destination.

Note: the source provider will not be deregistered. Note: a provider of the same type must exist at the designated destination address and ID.

Parameters

provider – Provider name.
dest_addr – Destination address.
dest_provider_id – Destination provider ID.
migration_config – Provider-specific JSON configuration.
remove_source – Whether to remove the source state.

void snapshotProvider(const std::string &provider, const std::string &dest_path, const std::string &snapshot_config, bool remove_source)

Snapshot the specified provider state to the destination path.

Parameters

provider – Provider name.
dest_path – Destination path.
snapshot_config – Provider-specific snapshot configuration.
remove_source – Whether to remove the source state.

void restoreProvider(const std::string &provider, const std::string &src_path, const std::string &restore_config)

Restore the specified provider state from the source path.

Parameters

provider – Provider name.
src_path – Source path.
restore_config – Provider-specific snapshot configuration.
remove_source – Whether to remove the source state.

json getCurrentConfig() const: Return the current JSON configuration.

bedrock::RequestResult

template<typename T> class RequestResult

The RequestResult object is a generic object used to hold and send back the result of an RPC. It contains three fields:

success must be set to true if the request succeeded, false otherwise
error must be set to an error string if an error occured
value must be set to the result of the request if it succeeded

This class is specialized for two types: bool and std::string. If bool is used, both the value and the success fields will be managed by the same underlying variable. If std::string is used, both the value and the error fields will be managed by the same underlying variable.

Template Parameters: T – Type of the result.

Public Functions

inline bool &success(): Whether the request succeeded.

inline const bool &success() const: Whether the request succeeded.

inline std::string &error(): Error string if the request failed.

inline const std::string &error() const: Error string if the request failed.

inline T &value(): Value if the request succeeded.

inline const T &value() const: Value if the request succeeded.

template<typename Archive> inline void serialize(Archive &a)

Serialization function for Thallium.

Template Parameters: Archive – Archive type.
Parameters: a – Archive instance.

bedrock::RequestResult<bool>

Warning

doxygenclass: Cannot find class “bedrock::RequestResult<bool>” in doxygen xml output for project “bedrock” from directory: /home/docs/checkouts/readthedocs.org/user_builds/mochi/checkouts/latest/docs/source/bedrock/doxygen

bedrock::RequestResult<std::string>

Warning

doxygenclass: Cannot find class “bedrock::RequestResult<std::string>” in doxygen xml output for project “bedrock” from directory: /home/docs/checkouts/readthedocs.org/user_builds/mochi/checkouts/latest/docs/source/bedrock/doxygen

bedrock::Server

class Server

The Server class is encapsulating everything needed for a Bedrock service to to be instaniated on a process. It is used in bin/bedrock.cpp.

Public Functions

Server(const std::string &address, const std::string &config = "", ConfigType configType = ConfigType::JSON, const Jx9ParamMap &jx9Params = Jx9ParamMap())

Constructor.

Parameters

address – Address of the server.
config – JSON or JX9 configuration script.
configType – type of configuration (JSON or JX9).
jx9Params – parameters to pass to Jx9 configuration.

Server(const Server&) = delete: Copy-constructor is deleted.

Server(Server&&) = delete: Move-constructor.

Server &operator=(const Server&) = delete: Copy-assignment operator is deleted.

Server &operator=(Server&&) = delete: Move-assignment operator is deleted.

~Server(): Destructor.

MargoManager getMargoManager() const: Get the underlying MargoManager.

ProviderManager getProviderManager() const: Get the underlying ProviderManager.

void waitForFinalize(): Blocks until the underlying margo instance is finalized.

void finalize(): Finalize the underlying margo instance.

std::string getCurrentConfig() const: Return the current JSON configuration.

bedrock::ServiceGroupHandle

class ServiceGroupHandle

A ServiceGroupHandle object is a handle for a remote resource on a set of servers. It enables invoking functionalities on all the underlying ServiceHandles.

Public Functions

ServiceGroupHandle(): Constructor. The resulting ServiceGroupHandle handle will be invalid.

ServiceGroupHandle(const ServiceGroupHandle&): Copy-constructor.

ServiceGroupHandle(ServiceGroupHandle&&): Move-constructor.

ServiceGroupHandle &operator=(const ServiceGroupHandle&): Copy-assignment operator.

ServiceGroupHandle &operator=(ServiceGroupHandle&&): Move-assignment operator.

~ServiceGroupHandle(): Destructor.

Client client() const: Returns the client this database has been opened with.

void refresh() const: If the ServiceGroupHandle was built from an SSG group or a Flock group, this function will refresh the group view.

size_t size() const: Return the number of underlying ServiceHandles.

ServiceHandle operator[](size_t i) const: Returns the i-th underlying ServiceHandle.

void getConfig(std::string *config, AsyncRequest *req = nullptr) const

Get the JSON configuration of a service process.

Parameters

config – [out] Resulting configuration.
req – [out] Asynchronous request to wait on, if provided.

void queryConfig(const std::string &script, std::string *result, AsyncRequest *req = nullptr) const

Send a Jx9 script to be executed by the server. In the Jx9 script, $__config__ represents the server’s configuration. The value of result will be set to the value returned by the script.

Parameters

script – Jx9 script.
result – Result from the script.
req – Asynchronous request to wait on, if provided.

operator bool() const: Checks if the ServiceGroupHandle instance is valid.

bedrock::ServiceHandle

class ServiceHandle

A ServiceHandle object is a handle for a remote resource on a server. It enables invoking the resource’s functionalities.

Public Functions

ServiceHandle(): Constructor. The resulting ServiceHandle handle will be invalid.

ServiceHandle(const ServiceHandle&): Copy-constructor.

ServiceHandle(ServiceHandle&&): Move-constructor.

ServiceHandle &operator=(const ServiceHandle&): Copy-assignment operator.

ServiceHandle &operator=(ServiceHandle&&): Move-assignment operator.

~ServiceHandle(): Destructor.

Client client() const: Returns the client this database has been opened with.

tl::provider_handle providerHandle() const: Returns the provider handle underlying the ServiceHandle.

void loadModule(const std::string &path, AsyncRequest *req = nullptr) const

Ask the remote service daemon to load a module library.

Parameters

path – Library path.
req – Asynchronous request to wait on, if provided.

void addProvider(const std::string &description, uint16_t *provider_id_out = nullptr, AsyncRequest *req = nullptr) const

Creates a provider on the target service daemon.

Parameters

description – JSON description of the provider.
req – Asynchronous request to wait on, if provided.

void changeProviderPool(const std::string &provider_name, const std::string &pool_name, AsyncRequest *req = nullptr) const

Request that a provider change its pool for another one.

Parameters

provider_name – Name of the provider.
pool_name – Name of the new pool.
req – Asynchronous request to wait on, if provided.

void migrateProvider(const std::string &provider, const std::string &dest_addr, uint16_t dest_provider_id, const std::string &migration_config, bool remove_source, AsyncRequest *req = nullptr) const

Migrates the specified provider state to the destination.

Note: the source provider will not be deregistered. Note: a provider of the same type must exist at the designated destination address and ID.

Parameters

provider – Provider name.
dest_addr – Destination address.
dest_provider_id – Destination provider ID.
migration_config – Provider-specific JSON configuration.
remove_source – Whether to remove the source state.
req – Asynchronous request to wait on, if provided.

void snapshotProvider(const std::string &provider, const std::string &dest_path, const std::string &snapshot_config, bool remove_source, AsyncRequest *req = nullptr) const

Snapshot the specified provider state to the destination path.

Parameters

provider – Provider name.
dest_path – Destination path.
snapshot_config – Provider-specific snapshot configuration.
remove_source – Whether to remove the source state.
req – Asynchronous request to wait on, if provided.

void restoreProvider(const std::string &provider, const std::string &src_path, const std::string &restore_config, AsyncRequest *req = nullptr) const

Restore the specified provider state from the source path.

Parameters

provider – Provider name.
src_path – Source path.
restore_config – Provider-specific snapshot configuration.
remove_source – Whether to remove the source state.
req – Asynchronous request to wait on, if provided.

void addPool(const std::string &config, AsyncRequest *req = nullptr) const

Adds an Argobots pool to the Margo instance of the target service.

Parameters

config – JSON configuration of the pool.
req – Asynchronous request to wait on, if provided.

void addXstream(const std::string &config, AsyncRequest *req = nullptr) const

Adds an Argobots xstream to the Margo instance of the target service.

Parameters

config – JSON configuration of the ES.
req – Asynchronous request to wait on, if provided.

void removePool(const std::string &name, AsyncRequest *req = nullptr) const

Removes an Argobots pool from the Margo instance of the target service.

Parameters

name – Name of the pool to remove.
req – Asynchronous request to wait on, if provided.

void removeXstream(const std::string &name, AsyncRequest *req = nullptr) const

Removes an Argobots xstream from the Margo instance of the target service.

Parameters

name – Name of the ES to remove.
req – Asynchronous request to wait on, if provided.

void getConfig(std::string *config, AsyncRequest *req = nullptr) const

Get the JSON configuration of a service process.

Parameters

config – [out] Resulting configuration.
req – [out] Asynchronous request to wait on, if provided.

void queryConfig(const std::string &script, std::string *result, AsyncRequest *req = nullptr) const

Send a Jx9 script to be executed by the server. In the Jx9 script, $__config__ represents the server’s configuration. The value of result will be set to the value returned by the script.

Parameters

script – Jx9 script.
result – Result from the script.
req – Asynchronous request to wait on, if provided.

operator bool() const: Checks if the ServiceHandle instance is valid.

bedrock::VoidPtr

Warning

doxygenclass: Cannot find class “bedrock::VoidPtr” in doxygen xml output for project “bedrock” from directory: /home/docs/checkouts/readthedocs.org/user_builds/mochi/checkouts/latest/docs/source/bedrock/doxygen