API Documentation

thallium::abt

class abt

Public Static Functions

static inline void initialize(): Initialize the Argobots execution environment.

static inline bool initialized()

Check whether Argobots has been initialized.

Returns: true if Argobots has been initialized.

static inline void finalize(): Finalizes Argobots.

thallium::abt_exception

class abt_exception : public thallium::exception : Exception class thrown by the abt class.

thallium::anonymous

Warning

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

thallium::async_response

class async_response

async_response objects are created by sending an RPC in a non-blocking way. They can be used to wait for the actual response.

Public Functions

async_response(const async_response &other) = delete: Copy constructor is deleted.

inline async_response(async_response &&other) noexcept

Move-constructor.

Parameters: other – async_response to move from.

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

inline async_response &operator=(async_response &&other) noexcept: Move-assignment operator. Will invalidate the moved-from object.

inline ~async_response() noexcept: Destructor.

inline packed_data wait()

Waits for the async_response to be ready and returns a packed_data when the response has been received.

Returns: a packed_data containing the response.

inline bool received() const

Tests without blocking if the response has been received.

Returns: true if the response has been received, false otherwise.

Public Static Functions

template<typename Iterator> static inline packed_data wait_any(const Iterator &begin, const Iterator &end, Iterator &completed)

Waits for any of the provided async_response to complete, and return a packed_data. The completed iterator will be set to point to the async_response that completed. This method may throw a timeout if any of the requests timed out, or other exceptions if an error happens. Even if an exception is thrown, the completed iterator will be correctly set to point to the async_response in cause.

Template Parameters

Iterator – Iterator type (e.g. std::vector<async_response>::iterator)

Parameters

begin – Begin iterator
end – End iterator

Returns

a packed_data.

thallium::barrier

class barrier

Wrapper for Argobots’ ABT_barrier.

Public Types

typedef ABT_barrier native_handle_type: Native handle type (ABT_barrier)

Public Functions

inline explicit barrier(uint32_t num_waiters)

Constructor.

Parameters: num_waiters – Number of waiters.

barrier(const barrier &other) = delete: Copy constructor is deleted.

barrier &operator=(const barrier &other) = delete: Copy assignment operator is deleted.

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

Move assignment operator.

If the right and left operands are different, this method will free the left operand’s resource (if necessary), and assign it the right operand’s resource. The right operand will be invalidated.

inline barrier(barrier &&other) noexcept

Move constructor. The right operand will be invalidated.

Parameters: other – barrier object to move from.

inline ~barrier() noexcept: Destructor.

inline void reinit(uint32_t num_waiters)

Reinitializes the barrier for a given number of waiters.

Parameters: num_waiters – Number of waiters.

inline void wait(): Waits on the barrier.

inline uint32_t get_num_waiters() const

Get the number of waiters that the barrier is expecting (passed to the constructor or to reinit).

Returns: The number of waiters.

inline native_handle_type native_handle() const noexcept

Get the underlying ABT_barrier handle.

Returns: the underlying ABT_barrier handle.

thallium::barrier_exception

class barrier_exception : public thallium::exception : Exception class thrown by the barrier class.

thallium::bulk

class bulk

bulk objects represent abstractions of memory segments exposed by a process for RDMA operations. A bulk object can be serialized to be sent over RPC to another process.

Public Functions

inline bulk() noexcept: Default constructor, defined so that one can have a bulk object as class member and associate it later with an actual bulk.

inline bulk(const bulk &other): Copy constructor.

inline bulk(bulk &&other) noexcept: Move constructor.

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

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

inline ~bulk() noexcept: Destructor.

inline std::size_t size() const noexcept

Returns the size of the data exposed by the bulk object.

Returns: size of data exposed by the bulk object.

inline std::uint32_t segment_count() const noexcept: Get total number of segments abstracted by bulk handle.

inline bool is_null() const noexcept

Indicates whether the bulk handle is null.

Returns: true if the bulk handle is null, false otherwise.

inline remote_bulk on(const endpoint &ep) const noexcept

Builds a remote_bulk object by associating it with an endpoint.

Parameters: ep – endpoint with which the bulk object should be associated.
Returns: a remote_bulk instance.

inline bulk_segment select(std::size_t offset, std::size_t size) const noexcept

Creates a bulk_segment object by selecting a given portion of the bulk object given an offset and a size.

Parameters

offset – Offset at which the segment starts.
size – Size of the segment.

Returns

a bulk_segment object.

inline bulk_segment operator()(std::size_t offset, std::size_t size) const noexcept

See also

bulk::select

inline std::size_t operator>>(const remote_bulk &b) const

Pushes data from the left operand (entire bulk object) to the right operand (remote_bulk). If the size of the segments don’t match, the smallest size is used.

Parameters: b – remote_bulk object towards which to push data.
Returns: the size of data transfered.

inline std::size_t operator<<(const remote_bulk &b) const

Pulls data from the right operand (remote_bulk) to the left operand (bulk). If the size of the segments don’t match, the smallest size is used.

Parameters: b – remote_bulk object from which to pull data.
Returns: the size of data transfered.

inline hg_bulk_t get_bulk(bool copy = false) const noexcept

Returns the underlying hg_bulk_t handle. If copy == false, the returned handle is a reference to the internal handle managed by this bulk object, it should not be destroyed by the user and its lifetime will not exceed that of the bulk object. If copy == true, the returned handle should be destroyed by the user.

Parameters: copy – whether to make a copy or not.
Returns: The underlying hg_bulk_t handle.

template<typename A> inline void serialize(A &ar)

Function that serializes a bulk object into/from an archive.

Template Parameters: A – Archive type.
Parameters: ar – archive.

thallium::bulk_segment

class bulk_segment

The bulk_segment class represents a portion (represented by offset and size) of a bulk object.

Public Functions

inline bulk_segment(const bulk &b) noexcept

Constructor. By default the size of the segment will be that of the underlying bulk object, and the offset is 0.

Parameters: b – Reference to the bulk object from which the segment is taken.

inline bulk_segment(const bulk &b, std::size_t offset, std::size_t size) noexcept

Constructor.

Parameters

b – Reference to the bulk object from which the segment is taken.
offset – Offset at which the segment starts.
size – Size of the segment.

bulk_segment(const bulk_segment&) = default: Copy constructor is deleted.

bulk_segment(bulk_segment&&) = default: Move constructor is default.

bulk_segment &operator=(const bulk_segment&) = default: Copy assignment operator is default.

bulk_segment &operator=(bulk_segment&&) = default: Move assignment operator is default.

~bulk_segment() = default: Destructor is default.

inline remote_bulk on(const endpoint &ep) const noexcept

Associates the bulk segment with an endpoint to represent a remote_bulk object.

Parameters: ep – Endpoint where the bulk object has bee created.
Returns: a remote_bulk object.

inline std::size_t operator>>(const remote_bulk &b) const

Pushes data from the left operand (bulk_segment) to the right operand (remote_bulk). If the size of the segments don’t match, the smallest size is used.

Parameters: b – remote_bulk object towards which to push data.
Returns: the size of data transfered.

inline std::size_t operator<<(const remote_bulk &b) const

Pulls data from the right operand (remote_bulk) to the right operand (bulk_segment). If the size of the segments don’t match, the smallest size is used.

Parameters: b – remote_bulk object from which to pull data.
Returns: the size of data transfered.

inline bulk_segment select(std::size_t offset, std::size_t size) const noexcept

Selects a subsegment from this segment. If the size is too large, the maximum possible size is chosen.

Parameters

offset – Offset of the subsegment relative to the current segment.
size – Size of the subsegment.

Returns

a new bulk_segment object.

inline bulk_segment operator()(std::size_t offset, std::size_t size) const noexcept

See also

bulk_segment::select.

thallium::callable_remote_procedure_with_context

template<typename ...CtxArg> class callable_remote_procedure_with_context

callable_remote_procedure_with_context objects represent an RPC ready to be called (using the parenthesis operator). It is created from a remote_procedure object using remote_procedure::on(endpoint).

Public Functions

inline callable_remote_procedure_with_context(const callable_remote_procedure_with_context &other): Copy-constructor.

inline callable_remote_procedure_with_context(callable_remote_procedure_with_context &&other) noexcept: Move-constructor.

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

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

inline ~callable_remote_procedure_with_context(): Destructor.

template<typename ...NewCtxArg> inline auto with_serialization_context(NewCtxArg&&... args) const

Create a new callable_remote_procedure_with_context with a new context bound to it.

Template Parameters: NewCtxArg –
Parameters: args – New context

template<typename ...T> inline packed_data operator()(const T&... args)

Operator to call the RPC. Will serialize the arguments in a buffer and send the RPC to the endpoint.

Template Parameters: T – Types of the parameters.
Parameters: t – Parameters of the RPC.
Returns: a packed_data object containing the returned value.

template<typename R, typename P, typename ...T> inline packed_data timed(const std::chrono::duration<R, P> &t, const T&... args)

Same as operator() but takes a first parameter representing a timeout (std::duration object). If no response is received from the server before this timeout, the request is cancelled and tl::timeout is thrown.

Template Parameters

R –
P –
T –

Parameters

t – Timeout.
args – Parameters of the RPC.

Returns

a packed_data object containing the returned value.

inline packed_data operator()() const

Operator to call the RPC without any argument.

Returns: a packed_data object containing the returned value.

template<typename R, typename P> inline packed_data timed(const std::chrono::duration<R, P> &t)

Same as operator() with only a timeout value.

Template Parameters

R –
P –

Parameters

t – Timeout.

Returns

a packed_data object containing the returned value.

template<typename ...T> inline async_response async(const T&... args)

Issues an RPC in a non-blocking way. Will serialize the arguments in a buffer and send the RPC to the endpoint.

Template Parameters: T – Types of the parameters.
Parameters: t – Parameters of the RPC.
Returns: an async_response object that the caller can wait on.

template<typename R, typename P, typename ...T> inline async_response timed_async(const std::chrono::duration<R, P> &t, const T&... args)

Asynchronous RPC call with a timeout. If the operation times out, the wait() call on the returned async_response object will throw a tl::timeout exception.

Template Parameters

R –
P –
T –

Parameters

t – Timeout.
args – Parameters of the RPC.

Returns

an async_response object that the caller can wait on.

inline async_response async()

Non-blocking call to the RPC without any argument.

Returns: an async_response object that the caller can wait on.

template<typename R, typename P> inline async_response timed_async(const std::chrono::duration<R, P> &t)

Same as async() but with a specified timeout.

Template Parameters

R –
P –

Parameters

t – Timeout.

Returns

an async_response object that the caller can wait on.

thallium::condition_variable

class condition_variable

Wrapper for Argobots’ ABT_cond.

Public Types

typedef ABT_cond native_handle_type: Native handle type.

Public Functions

inline native_handle_type native_handle() const noexcept

Returns the underlying ABT_cond handle.

Returns: the underlying ABT_cond handle.

inline condition_variable(): Constructor.

inline ~condition_variable() noexcept: Destructor.

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

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

inline condition_variable &operator=(condition_variable &&other): Move assignment operator. If the left and right operands are different, this will move the right condition_variable’s resources to the left condition_variable, leaving the right one invalid.

inline condition_variable(condition_variable &&other) noexcept: Move constructor. This function will invalidate the passed condition_variable.

inline void wait(std::unique_lock<mutex> &lock)

Wait on a condition variable.

Parameters: lock – Mutex to lock when the condition is satisfied.

template<class Predicate> inline void wait(std::unique_lock<mutex> &lock, Predicate &&pred)

Wait on a condition variable until a predicate becomes true.

Template Parameters

Predicate – predicate type, must have parenthesis operator returning bool

Parameters

lock – Mutex to lock when the condition is satisfied.
pred – Predicate to test.

inline void notify_one(): Notify one waiter.

inline void notify_all(): Notify all waiters.

inline bool wait_until(std::unique_lock<mutex> &lock, const struct timespec *abstime)

Wait on a condition variable until a specific point in time.

Parameters

lock – Mutex to lock when condition variable is satisfied.
abstime – Date until which to wait.

Returns

true if lock was acquired, false if timeout

thallium::condition_variable_exception

class condition_variable_exception : public thallium::exception : Exception class thrown by the condition_variable class.

thallium::endpoint

class endpoint

endpoint objects represent an address to which RPC can be sent. They are created using engine::lookup().

Subclassed by thallium::provider_handle

Public Functions

inline endpoint(const engine &e, hg_addr_t addr, bool take_ownership = true)

Constructor. Made private since endpoint instances can only be created using engine::lookup.

Parameters

e – Engine that created the endpoint.
addr – Mercury address.

inline endpoint() noexcept: Default constructor defined so that endpoints can be member of other objects and assigned later.

inline endpoint(const endpoint &other): Copy constructor.

inline endpoint(endpoint &&other) noexcept: Move constructor.

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

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

inline virtual ~endpoint(): Destructor.

inline operator std::string() const

Creates a string representation of the endpoint’s address.

Returns: A string representation of the endpoint’s address.

inline bool is_null() const noexcept

Indicates whether the endpoint is null or not.

Returns: true if the endpoint is a null address.

inline hg_addr_t get_addr(bool copy = false) const

Returns the underlying Mercury address.

Parameters: copy – If set to true, a copy of the address will be made. (the user will be responsible for calling margo_addr_free on this address) Otherwise, the hg_addr_t returned is the one managed by the endpoint instance and will be deleted when this enpoint is destroyed.
Returns: The underlying hg_addr_t.

inline bool operator==(const endpoint &other) const: Compares two addresses for equality.

inline void set_remove(): Hint that the address is no longer valid. This may happen if the peer is no longer responding. This can be used to force removal of the peer address from the list of the peers, before freeing it and reclaim resources.

Friends

template<typename S> friend S &operator<<(S &s, const endpoint &e)

Streaming operator for endpoint, converts the endpoint into a string before feeding it to the string operator. This enables, for instance, streaming the endpoint into std::cout for logging without having to explicitely convert it into a string.

Template Parameters

S – Type of stream.

Parameters

s – Stream.
e – Endpoint.

Returns

Reference to the provided stream.

thallium::engine

class engine

The engine class is at the core of Thallium, it is the first object to instanciate to start using the Thallium runtime. It initializes Margo and other libraries, and allow users to declare RPCs and bulk objects.

Public Functions

engine() = default: The default constructor is there to handle the case of declaring and assigning the engine in different places of the code.

inline engine(const std::string &addr, int mode, const margo_init_info *args)

Constructor.

Parameters

addr – address of this instance.
mode – THALLIUM_SERVER_MODE or THALLIUM_CLIENT_MODE.
args – pointer to a margo_init_info structure to pass to margo.

inline engine(const std::string &addr, int mode, bool use_progress_thread = false, std::int32_t rpc_thread_count = 0, const hg_init_info *hg_opt = nullptr)

Constructor.

Parameters

addr – address of this instance.
mode – THALLIUM_SERVER_MODE or THALLIUM_CLIENT_MODE.
use_progress_thread – whether to use a dedicated ES to drive progress.
rpc_thread_count – number of threads to use for servicing RPCs. Use -1 to indicate that RPCs should be serviced in the progress ES.
hg_opt – options for initializing Mercury.

inline engine(const std::string &addr, int mode, const char *config, const hg_init_info *hg_opt = nullptr)

Constructor.

Parameters

addr – address of this instance.
mode – THALLIUM_SERVER_MODE or THALLIUM_CLIENT_MODE.
config – JSON configuration.
hg_opt – options for initializing Mercury. Use -1 to indicate that RPCs should be serviced in the progress ES.

inline engine(margo_instance_id mid) noexcept

Builds an engine around an existing margo instance.

Parameters: mid – Margo instance.

engine(const engine &other) = default: Copy-constructor.

engine(engine &&other) = default: Move-constructor. This method will invalidate the engine that is moved from.

inline engine &operator=(engine &&other): Move-assignment operator. This method will invalidate the engine that it moved from.

inline engine &operator=(const engine &other): Copy-assignment operator is deleted.

inline ~engine(): Destructor.

inline margo_instance_id get_margo_instance() const

Get the underlying margo instance. Useful when working in conjunction with C code that need to be initialized with the margo instance.

Returns: The margo instance id.

inline void finalize(): Finalize the engine. Can be called by any thread.

inline void wait_for_finalize(): Makes the calling thread block until someone calls finalize on this engine. This function will not do anything if finalize was already called.

inline endpoint self() const

Creates an endpoint from this engine.

Returns: An endpoint corresponding to this engine.

inline remote_procedure define(const std::string &name)

Defines an RPC with a name, without providing a function pointer (used on clients).

Parameters: name – Name of the RPC.
Returns: a remote_procedure object.

template<typename A1, typename ...Args> remote_procedure define(const std::string &name, const std::function<void(const request&, A1, Args...)> &fun, uint16_t provider_id, const pool &p)

Defines an RPC with a name and an std::function representing the RPC.

Template Parameters

Args – Types of arguments accepted by the RPC.

Parameters

name – Name of the RPC.
fun – Function to associate with the RPC.
provider_id – ID of the provider registering this RPC.
pool – Argobots pool to use when receiving this type of RPC

Returns

a remote_procedure object.

template<typename ...Args> remote_procedure define(const std::string &name, void (*f)(const request&, Args...), uint16_t provider_id, const pool &p)

Defines an RPC with a name and a function pointer to call when the RPC is received.

Template Parameters

Args – Types of arguments accepted by the RPC.

Parameters

name – Name of the RPC.
f – Function to associate with the RPC.
provider_id – ID of the provider registering this RPC.
pool – Argobots pool to use when receiving this type of RPC.

Returns

a remote_procedure object.

inline endpoint lookup(const std::string &address) const

Lookup an address and returns an endpoint object to communicate with this address.

Parameters: address – String representation of the address.
Returns: an endpoint object associated with the given address.

inline bulk expose(const std::vector<std::pair<void*, size_t>> &segments, bulk_mode flag)

Exposes a series of memory segments for bulk operations.

Parameters

segments – vector of <pointer,size> pairs of memory segments.
flag – indicates whether the bulk is read-write, read-only or write-only.

Returns

a bulk object representing the memory exposed for RDMA.

inline bulk wrap(hg_bulk_t blk, bool is_local)

Creates a bulk object from an hg_bulk_t handle. The user is still responsible for calling margo_bulk_free or HG_Bulk_free on the original handle (this function will increment the hg_bulk_t’s internal reference counter).

Parameters

blk – Bulk handle.
is_local – Whether the bulk handle refers to memory that is local.

Returns

a bulk object representing the memory exposed for RDMA.

template<typename F> inline void push_prefinalize_callback(F &&f)

Pushes a pre-finalization callback into the engine. This callback will be called when margo_finalize is called (e.g. through engine::finalize()), before the Mercury progress loop is terminated.

Template Parameters: F – type of callback. Must have a operator() defined.
Parameters: f – callback.

template<typename F> inline void push_prefinalize_callback(const void *owner, F &&f)

Same as push_prefinalize_callback(F&& f) but takes an object whose address will be used to identify the callback (e.g. a provider).

Template Parameters

F – Callback type.

Parameters

owner – Pointer to the object owning the callback.
f – Callback.

inline std::function<void(void)> top_prefinalize_callback() const

Gets the most recently pushed pre-finalization callback and returns it. If no finalization callback are present, this function returns a null std::function.

Returns: finalization callback.

inline std::function<void(void)> top_prefinalize_callback(const void *owner) const

Gets the most recently pushed pre-finalization callback pushed for a given owner.

Parameters: owner – Pointer to the owner.
Returns: finalization callback.

inline std::function<void(void)> pop_prefinalize_callback()

Pops the most recently pushed pre-finalization callback and returns it. If no finalization callback are present, this function returns a null std::function.

Returns: finalization callback.

inline std::function<void(void)> pop_prefinalize_callback(const void *owner)

Pops the most recently pushed pre-finalization callback pushed for a given owner.

Parameters: owner – Pointer to the owner.
Returns: finalization callback.

template<typename F> inline void push_finalize_callback(F &&f)

Pushes a finalization callback into the engine. This callback will be called when margo_finalize is called (e.g. through engine::finalize()).

Template Parameters: F – type of callback. Must have a operator() defined.
Parameters: f – callback.

template<typename F> inline void push_finalize_callback(const void *owner, F &&f)

Same as push_finalize_callback(F&& f) but takes an object whose address will be used to identify the callback (e.g. a provider).

Template Parameters

T – Type of object used to identify the callback.
F – Callback type.

Parameters

owner – Pointer to the object owning the callback.
f – Callback.

inline std::function<void(void)> top_finalize_callback() const

Getss the most recently pushed finalization callback and returns it. If no finalization callback are present, this function returns a null std::function.

Returns: finalization callback.

inline std::function<void(void)> top_finalize_callback(const void *owner) const

Gets the most recently pushed finalization callback pushed for a given owner.

Parameters: owner – Pointer to the owner.
Returns: finalization callback.

inline std::function<void(void)> pop_finalize_callback()

Pops the most recently pushed finalization callback and returns it. If no finalization callback are present, this function returns a null std::function.

Returns: finalization callback.

inline std::function<void(void)> pop_finalize_callback(const void *owner)

Pops the most recently pushed finalization callback pushed for a given owner.

Parameters: owner – Pointer to the owner.
Returns: finalization callback.

inline void shutdown_remote_engine(const endpoint &ep) const

Shuts down a remote thallium engine. The remote engine should have enabled remote shutdown by calling enable_remote_shutdown().

Parameters: ep – endpoint of the remote engine.

inline void enable_remote_shutdown(): Enables this engine to be shutdown remotely.

inline bool is_listening() const: Checks if the engine is listening for incoming RPCs.

inline pool get_handler_pool() const

Get the handler’s pool.

Returns: The default pool used for RPC handlers.

inline pool get_progress_pool() const

Get the progress pool.

Returns: The pool used for network progress.

template<typename F> inline timed_callback create_timed_callback(F &&cb) const

Create a timed_callback object linked to the engine.

Template Parameters: F – Callback type.
Parameters: cb – Callback
Returns: a timed_callback object.

inline std::string get_config() const: Get the JSON configuration of the internal Margo instance.

inline list_proxy<xstream, ABT_xstream> xstreams() const: Returns a proxy object that can be used to access the internal list of xstreams in the underlying margo instance.

inline list_proxy<pool, ABT_pool> pools() const: Returns a proxy object that can be used to access the internal list of pools in the underlying margo instance.

template<typename T> struct named_object_proxy : public T 

thallium::eventual

template<typename T> class eventual

The eventual class wraps an ABT_eventual object. It is a template class, with the template type T being the object stored by the eventual. T must be default-constructible and assignable.

Public Types

using value_type = typename std::remove_reference<typename std::remove_cv<T>::type>::type: Type of value stored by the eventual.

using native_handle_type = ABT_eventual: Native handle type.

Public Functions

inline ABT_eventual native_handle() const noexcept

Get the underlying native handle.

Returns: The underlying native handle.

inline eventual(): Constryctor.

inline ~eventual(): Destructor.

eventual(const eventual &other) = delete: Copy constructor is deleted.

eventual &operator=(const eventual &other) = delete: Copy assignment operator is deleted.

inline eventual &operator=(eventual &&other): Move assignment operator. If the left and right operands are different, this function will assign the right operand’s resource to the left. This invalidates the right operand.

inline eventual(eventual &&other): Move constructor.

inline void set_value(const T &val)

Set the eventual’s value (by copy).

Parameters: val – Value to give the eventual.

inline void set_value(T &&val)

Set the eventual’s value (by moving).

Parameters: val – Value to give the eventual.

inline value_type wait()

Wait on the eventual.

Returns: The value stored in the eventual.

inline bool test(): Test the eventual.

inline void reset(): Reset the eventual.

thallium::eventual<void>

Warning

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

thallium::eventual_exception

class eventual_exception : public thallium::exception : Exception class thrown by the eventual class.

thallium::exception

class exception : public exception : Subclassed by thallium::abt_exception, thallium::barrier_exception, thallium::condition_variable_exception, thallium::eventual_exception, thallium::future_exception, thallium::margo_exception, thallium::mutex_exception, thallium::pool_exception, thallium::rwlock_exception, thallium::scheduler_exception, thallium::self_exception, thallium::task_exception, thallium::thread_exception, thallium::timer_exception, thallium::xstream_barrier_exception, thallium::xstream_exception

thallium::future

template<typename T> class future

The future class wraps an ABT_future oject. A future holds an array of pointers to objects of type T. The future is not responsible for managing/freeing these objects.

Public Types

typedef ABT_future native_handle_type: Type of the underlying native handle.

Public Functions

inline native_handle_type native_handle() const noexcept

Get the underlying native handle.

Returns: The underlying native handle.

inline future(uint32_t compartments)

Constructor.

Parameters: compartments – Number of objects expected before the future is ready.

template<typename F> inline future(uint32_t compartments, F &&cb_fun)

Constructor.

Template Parameters

F – Type of callback.

Parameters

compartments – Number of objects expected before the future is ready.
cb_fun – Function to call when the future becomes ready.

future(const future &other) = delete: Copy constructor is deleted.

inline future(future &&other) noexcept: Move constructor.

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

inline future &operator=(future &&other): Move assignment operator.

inline void wait(): Wait for the future to be ready.

inline bool test() const: Test is the future is ready.

inline operator bool() const

See also

future::test

inline void set(T *value)

Set one of the future’s values.

Parameters: value – pointer to the value to set.

inline ~future(): Destructor.

thallium::future_exception

class future_exception : public thallium::exception : Exception class thrown by the future class.

thallium::logger

class logger

The logger class is an abstract class that users can inherit from to provide custom logging capabilities to the margo instance underlying a thallium engine.

An pointer to a logger can be passed to engine::set_logger.

thallium::managed

template<class T> class managed

The manager<T> class is used to automatically free a resource holder (e.g. thread, task, xstream, pool, scheduler) that would otherwise not free its underlying Argobots resource upon destruction. This class acts like a smart pointer.

Template Parameters: T – Type of resource holder.

Public Functions

managed(const managed&) = delete: Deleted copy constructor.

inline managed(managed &&other): Move constructor.

managed &operator=(const managed&) = delete: Deleted copy-assignment operator.

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

inline ~managed(): Destructor.

inline T &operator*(): Dereference operator.

inline T *operator->(): Pointer access operator.

thallium::margo_exception

class margo_exception : public thallium::exception 

Exception class used when margo functions fail.

Public Functions

inline margo_exception(const std::string &function, const std::string file, unsigned line, hg_return_t ret, const std::string &message = std::string())

Constructor.

Parameters

function – Name of the function that failed.
file – Name of the file where the exception was thrown.
line – Line in the file.
message – Additional message.

thallium::mutex

class mutex

The mutex class is an equivalent of std::mutex but build around Argobot’s mutex.

Subclassed by thallium::recursive_mutex

Public Types

typedef ABT_mutex native_handle_type: Type of the underlying native handle.

Public Functions

inline explicit mutex(bool recursive = false)

Constructor.

Parameters: recursive – whether the mutex is recursive or not.

mutex(const mutex &other) = delete: Copy constructor is deleted.

mutex &operator=(const mutex &other) = delete: Copy assignment operator is deleted.

inline mutex &operator=(mutex &&other): Move assignment operator is deleted.

inline mutex(mutex &&other) noexcept: Move constructor.

inline virtual ~mutex() noexcept: Destructor.

inline void lock(): Lock the mutex.

inline void lock_low(): Lock the mutex in low priority.

inline void spin_lock(): Lock the mutex without context switch.

inline bool try_lock()

Try locking the mutex without blocking.

Returns: true if it managed to lock the mutex.

inline void unlock(): Unlock the mutex.

inline void unlock_se(): Hand over the mutex within the ES.

inline ABT_mutex native_handle() const noexcept

Get the underlying native handle.

Returns: the underlying native handle.

thallium::mutex_exception

class mutex_exception : public thallium::exception : Exception class thrown by the mutex class.

thallium::output_archive

Warning

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

thallium::packed_data

template<typename ...CtxArg> class packed_data

packed_data objects encapsulate data serialized into an hg_handle_t, whether it is input or output data.

Public Functions

inline hg_handle_t native_handle() const: Return the request’s underlying hg_handle_t.

template<typename ...NewCtxArg> inline auto with_serialization_context(NewCtxArg&&... args)

Create a new packed_data object but with a different serialization context.

Template Parameters: NewCtxArg – Types of the serialization context.
Parameters: args – Context.

template<typename T> inline T as() const

Converts the handle’s content into the requested object.

Template Parameters: T – Type into which to convert the content of the buffer.
Returns: Buffer converted into the desired type.

template<typename T1, typename T2, typename ...Tn> inline auto as() const

Converts the content of the buffer into a std::tuple of types T1, T2, … Tn.

This function allows to do something like the following: int x; double y; std::tie(x,y) = pack.as<int,double>();

Template Parameters

T1 – First type of the tuple.
T2 – Second type of the tuple.
Tn – Other types of the tuple.

Returns

buffer content converted into the desired std::tuple.

template<typename T> inline operator T() const

Converts the content of the packed_data into the desired object type. Allows to cast the packed_data into the desired object type.

Template Parameters: T – Type into which to convert the response.
Returns: An object of the desired type.

thallium::pool

class pool

Wrapper for Argobots’ ABT_pool.

NOTE: This class does not provide all the functionalities of Argobot’s pool, in particular custom definitions.

Public Types

enum class access : std::int32_t

Types of accesses enabled by the pool: private, single-producer-single-consumer, multiple-producer-single-consumer, single- producer-multiple-consumer, or multiple-producer- multiple-consumer.

Values:

enumerator priv

enumerator spsc

enumerator mpsc

enumerator spmc

enumerator mpmc

enum class kind : std::int32_t

Kind of pool.

Values:

enumerator fifo

enumerator fifo_wait

typedef ABT_pool native_handle_type: Type of the underlying native handle.

Public Functions

inline explicit pool(ABT_pool p) noexcept

Constructor used to build a pool out of an existing handle.

Parameters: p – existing ABT_pool handle. May be null.

inline pool() noexcept: Default constructor handles a null pool.

inline native_handle_type native_handle() const noexcept

Get the underlying native handle.

Returns: the underlying native handle.

pool(const pool &other) = default: Copy constructor.

inline pool(pool &&other) noexcept: Move constructor.

pool &operator=(const pool &other) = default: Copy assignment operator.

inline pool &operator=(pool &&other) noexcept: Move assignment operator.

~pool() = default: Destructor.

inline bool is_null() const noexcept

Check if the underlying pool handle is null.

Returns: true if the pool handle is null, false otherwise.

inline operator bool() const noexcept: Returns true if the pool handle is not null.

inline access get_access() const

Get the access type of the pool.

Returns: the access type of the pool.

inline std::size_t total_size() const

Get the total number of elements present in the pool, including blocked ULTs and migrating ULTs.

Returns: total number of elements in the pool.

inline std::size_t size() const

Get the number of elements in the pool, not including the ULTs that are blocked.

Returns: the number of elements in the pool.

inline int id() const

Get the id of the pool.

Returns: the id of the pool.

template<typename U> inline U *pop()

Pops a unit of work out of the pool.

Template Parameters: U – Type of the unit of work.
Returns: A pointer to a unit of work.

template<typename U> inline void push(U *unit)

Pushes a unit of work into the pool. The pool must be a custom pool that manages units of type U. The work unit must have been popped from a pool managing the same type of work units U. The work unit must not have been created manually.

Template Parameters: U – type of work unit.
Parameters: unit – work unit.

template<typename U> inline void remove(U *unit)

Removes a work unit from the pool. The pool must be a custom pool that manages units of type U.

Template Parameters: U – type of work unit.
Parameters: unit – work unit.

template<typename U> inline void run_unit(U *unit)

This function should be called inside a custom scheduler to run a work unit on the ES the scheduler runs on. The type of work unit U should match the type used by the custom pool.

Template Parameters: U – type of work unit.
Parameters: unit – Work unit.

inline void add_sched(const scheduler &sched)

Push a scheduler to a pool. By pushing a scheduler, the user can change the running scheduler: when the top scheduler (the running scheduler) will pick it from the pool and run it, it will become the new scheduler. This new scheduler will be in charge until it explicitly yields, except if scheduler::finish() or scheduler::exit() are called.

Parameters: sched – Scheduler to push.

template<typename F> managed<task> make_task(F &&f)

Create a task running the specified function and push it into the pool.

Template Parameters: F – type of function to run as a task. Must have operator()().
Parameters: f – Function to run as a task.
Returns: a task object managing the created task.

template<typename F> managed<thread> make_thread(F &&f)

Create a thread running the specified function and push it into the pool.

Template Parameters: F – type of function to run as a task. Must have operator()().
Parameters: f – Function to run as a task.
Returns: a thread object managing the created thread.

template<typename F, typename Attr> managed<thread> make_thread(F &&f, const Attr &attr)

Create a thread running the specified function and push it into the pool.

Template Parameters

F – type of function to run as a task. Must have operator()().
Attr – type of thread attribute (must be thread::attribute).

Parameters

f – Function to run as a task.
attr – Thread attributes.

Returns

a thread object managing the created thread.

template<typename F> void revive_thread(thread &t, F &&fun)

Use an existing thread that has been joined to start working on a new function.

Template Parameters

F – Function type

Parameters

t – thread to revive
fun – Function

template<typename F> void revive_task(task &t, F &&fun)

Use an existing task that has been joined to start working on a new function.

Template Parameters

F – Function type

Parameters

t – task to revive
fun – Function

Public Static Functions

template<typename P, typename U, typename Palloc = std::allocator<P>, typename Ualloc = std::allocator<U>> static inline managed<pool> create()

Create a pool with user-provided pool type P and unit type U. Returns it as a managed<pool> object.

IMPORTANT: The destructor of a managed<pool> will try to destroy the pool. If the pool is still attached to a scheduler, this will cause undefined behaviors. Make sure all the schedulers that use this pool have been destroyed before the pool goes out of scope.

The type of unit U should adhere to the following model:

class U {
  public:
    // initialization from a thread
    Unit(const thread& t);
    // initialization from a task
    Unit(const task& t);
    // returns the type of unit
    unit_type get_type() const;
    // returns a thread if the unit_type is thread
    const tl::thread& get_thread() const;
    // returns a task if the unit_type is task
    const tl::task& get_task() const;
    // returns whether the unit is in a pool
    bool is_in_pool() const;
};

The type of pool P should adhere to the following model:

class Pool {
  public:
    // access type
    static const pool::access access_type;
    // get the size of the pool
    size_t get_size() const;
    // push a unit into the pool
    void push(U* u);
    // pop a unit from the pool
    my_unit* pop();
    // remove a unit from the pool
    void remove(my_unit* u);
};

Template Parameters

P – Custom pool type
U – Custom unit type
Palloc – Special allocator to allocate a pool
Ualloc – Special allocator to allocate a unit

Returns

a managed<pool> object.

static inline managed<pool> create(access a, kind k = kind::fifo)

Builds a pool using a default implementation from Argobots.

IMPORTANT: The destructor of a managed<pool> will try to destroy the pool. If the pool is still attached to a scheduler, this will cause undefined behaviors. Make sure all the schedulers that use this pool have been destroyed before the pool goes out of scope.

Parameters

access – Access type enabled by the pool.
kind – Kind of pool (fifo or fifo_wait).

thallium::pool_exception

class pool_exception : public thallium::exception : Exception class thrown by the pool class.

thallium::proc_input_archive

template<typename ...CtxArg> class proc_input_archive

proc_input_archive wraps a hg_proc_t object and offers the functionalities to deserialize its content into C++ objects. It inherits from the input_archive trait so that serialization methods know they have to take data out of the buffer and into C++ objects.

Public Functions

inline proc_input_archive(hg_proc_t p, std::tuple<CtxArg...> &context, const std::weak_ptr<detail::engine_impl> &e)

Constructor.

Parameters

p – : hg_proc_t from which to read.
engine – : thallium engine.

template<typename T> inline proc_input_archive &operator&(T &&obj): Operator to get C++ objects of type T from the archive. The object should either be a basic type, or an STL container (in which case the appropriate thallium/serialization/stl/ header should be included for this function to be properly instanciated), or any object for which either a serialize member function or a load member function has been provided.

template<typename T> inline proc_input_archive &operator()(T &&obj): Parenthesis operator with one argument, equivalent to & operator.

template<typename T, typename ...Targs> inline proc_input_archive &operator()(T &&obj, Targs&&... others): Parenthesis operator with multiple arguments. ar(x,y,z) is equivalent to ar & x & y & z.

template<typename T> inline proc_input_archive &operator>>(T &&obj)

Operator >> is equivalent to operator &.

See also

operator&

template<typename T> inline void read(T *t, std::size_t count = 1): Basic function to read count objects of type T from the buffer. A memcopy is performed from the buffer to the object, so the object should either be a basic type or an object that can be memcopied instead of calling a more elaborate serialize function.

template<typename T> inline void copy(T *t, std::size_t count = 1): Equivalent to read().

inline const std::weak_ptr<detail::engine_impl> &get_engine_impl() const

Returns the engine impl registered in the archive.

Returns: The engine impl registered in the archive.

inline hg_proc_t get_proc() const: Returns the hg_proc_t object handling the current serialization.

inline auto &get_context(): Retrieve context objects bound with the archive.

thallium::proc_output_archive

template<typename ...CtxArg> class proc_output_archive

proc_output_archive wraps an hg_proc_t object and offers the functionalities to serialize C++ objects into it.

Public Functions

inline proc_output_archive(hg_proc_t p, std::tuple<CtxArg...> &context, std::weak_ptr<detail::engine_impl> e)

Constructor.

Parameters

p – : reference to an hg_proc_t object.
e – : thallium engine.

template<typename T> inline proc_output_archive &operator&(T &&obj): Operator to add a C++ object of type T into the archive. The object should either be a basic type, or an STL container (in which case the appropriate header should be included for this function to be properly instanciated), or any object for which either a serialize member function or a load member function has been provided.

template<typename T> inline proc_output_archive &operator()(T &&obj): Parenthesis operator with one argument, equivalent to & operator.

template<typename T, typename ...Targs> inline proc_output_archive &operator()(T &&obj, Targs&&... others): Parenthesis operator with multiple arguments. ar(x,y,z) is equivalent to ar & x & y & z.

template<typename T> inline proc_output_archive &operator<<(T &&obj)

Operator << is equivalent to operator &.

See also

operator&

template<typename T> inline void write(const T *const t, size_t count = 1): Basic function to write count objects of type T into the buffer. A memcopy is performed from the object’s address to the buffer, so the object should either be basic type or an object that can be memcopied instead of calling a more elaborate serialize function.

template<typename T> inline void copy(T *const t, size_t count = 1): Equivalent to write().

inline const std::weak_ptr<detail::engine_impl> &get_engine_impl() const

Returns the engine registered in the archive.

Returns: The engine registered in the archive.

inline hg_proc_t get_proc() const: Returns the hg_proc_t object handling the current serialization.

inline auto &get_context(): Retrieve context objects bound with the archive.

thallium::provider

template<typename T> class provider

The provider class represents an object that exposes its member functions as RPCs. It is a template class meant to be used as base class for other objects. For example: class MyProvider : public thallium::provider<MyProvider> { … };.

Template Parameters: T –

Public Functions

provider(const provider &other) = delete: Copy-constructor.

provider(provider &&other) = delete: Move-constructor.

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

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

inline engine get_engine() const

Get the engine associated with this provider.

Returns: The engine associated with this provider.

inline uint16_t get_provider_id() const

Get the provider id.

Returns: The provider id.

thallium::provider_handle

class provider_handle : public thallium::endpoint 

The provider_handle class encapsulates an enpoint with a provider id to reference a particular provider object at a given address. provider_handle inherites from endpoint so it can be used wherever endpoint is needed.

Public Functions

inline provider_handle(const engine &e, hg_addr_t addr, uint16_t provider_id = 0, bool take_ownership = true)

Constructor from a HG address.

Parameters

e – engine.
addr – Address to encapsulate.
provider_id – provider id.

inline provider_handle(endpoint e, uint16_t provider_id = 0)

Constructor.

Parameters

e – enpoint to encapsulate.
provider_id – provider id.

provider_handle() = default: Default constructor defined so that provider_handlers can be member of other objects and assigned later.

provider_handle(const provider_handle &other) = default: Copy constructor.

provider_handle(provider_handle &&other) = default: Move constructor.

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

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

~provider_handle() = default: Destructor.

inline uint16_t provider_id() const

Get the provider id.

Returns: the provider id.

thallium::recursive_mutex

class recursive_mutex : public thallium::mutex 

Child class of mutex to represent a recursive mutex.

Public Functions

inline recursive_mutex(): Constructor.

recursive_mutex(const recursive_mutex &other) = delete: Copy constructor is deleted.

inline recursive_mutex(recursive_mutex &&other): Move constructor.

recursive_mutex &operator=(const recursive_mutex &other) = delete: Copy assignment operator is deleted.

recursive_mutex &operator=(recursive_mutex &&other) = default: Move assignment operator.

thallium::remote_bulk

class remote_bulk

A remote_bulk object represents a bulk_segment object that has been associated with an endpoint and is ready for RDMA operations.

Public Functions

remote_bulk(const remote_bulk&) = default: Default copy constructor.

remote_bulk(remote_bulk&&) = default: Default move constructor.

remote_bulk &operator=(const remote_bulk&) = default: Default copy-assignment operator.

remote_bulk &operator=(remote_bulk&&) = default: Default move-assignment operator.

inline std::size_t operator>>(const bulk_segment &dest) const

Performs a pull operation from the remote_bulk (left operand) to the destination bulk (right operand). The destination must be local. If the sizes don’t match, the smallest size is picked.

Parameters: dest – Local bulk segment on which to pull the data.
Returns: the size of data transfered.

inline std::size_t operator<<(const bulk_segment &src) const

Performs a push operation from the source bulk (right operand) to the remote_bulk (left operand). The source must be local. If the sizes don’t match, the smallest size is picked.

Parameters: src – Local bulk segment from which to push the data.
Returns: the size of data transfered.

inline remote_bulk select(std::size_t offset, std::size_t size) const

Creates a bulk_segment object by selecting a given portion of the bulk object given an offset and a size.

Parameters

offset – Offset at which the segment starts.
size – Size of the segment.

Returns

a bulk_segment object.

inline remote_bulk operator()(std::size_t offset, std::size_t size) const

See also

remote_bulk::select

thallium::remote_procedure

class remote_procedure

remote_procedure objects are produced by engine::define() when defining an RPC. Using remote_procedure::on(endpoint) creates a callable_remote_procedure that can be called with some parameters to send an RPC.

Public Functions

remote_procedure(const remote_procedure &other) = default: Copy-constructor is default.

remote_procedure(remote_procedure &&other) = default: Move-constructor is default.

remote_procedure &operator=(const remote_procedure &other) = default: Copy-assignment operator is default.

remote_procedure &operator=(remote_procedure &&other) = default: Move-assignment operator is default.

~remote_procedure() = default: Destructor is default.

inline callable_remote_procedure on(const endpoint &ep) const

Creates a callable_remote_procedure by associating the remote_procedure with an endpoint.

Parameters: ep – endpoint with which to associate the procedure.
Returns: a callable_remote_procedure.

inline callable_remote_procedure on(const provider_handle &ph) const

Creates a callable remote_procedure by associating the remote_procedure with a particular provider_handle.

Parameters: ph – provider_handle with which to associate the procedure.
Returns: a callable_remote_procedure.

inline remote_procedure &disable_response()

Tell the remote_procedure that it should not expect responses.

Returns: *this

inline void deregister(): Deregisters this RPC from the engine.

thallium::request_with_context

template<typename ...CtxArg> class request_with_context

A request_with_context object is created whenever a server receives an RPC. The object is passed as first argument to the function associated with the RPC. The request_with_context allows one to get information from the caller and to respond to the RPC.

Public Functions

inline request_with_context(const request_with_context &other): Copy constructor.

inline request_with_context(request_with_context &&other) noexcept: Move constructor.

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

inline request_with_context &operator=(request_with_context &&other) noexcept: Move-assignment operator.

inline ~request_with_context(): Destructor.

inline hg_handle_t native_handle() const: Return the request’s underlying hg_handle_t.

inline auto get_input() const: Get the input of the RPC as a packed_data object.

template<typename ...NewCtxArg> inline auto with_serialization_context(NewCtxArg&&... args) const

Create a new request_with_context object with a new context bound to it for response serialization.

Template Parameters: NewCtxArg –
Parameters: args – New context.

template<typename T1, typename ...T> inline void respond(T1 &&t1, T&&... t) const

Responds to the sender of the RPC. Serializes the series of arguments provided and send the resulting buffer to the sender.

Template Parameters: T – Types of parameters to serialize.
Parameters: t – Parameters to serialize.

inline endpoint get_endpoint() const

Get the endpoint corresponding to the sender of the RPC.

Returns: endpoint corresponding to the sender of the RPC.

thallium::rwlock

class rwlock

The rwlock class wraps and managed an ABT_rwlock.

Public Types

typedef ABT_rwlock native_handle_type: Native handle type.

Public Functions

inline explicit rwlock(): Constructor.

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

inline rwlock(rwlock &&other): Move constructor.

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

inline rwlock &operator=(rwlock &&other): Move assignment operator.

inline ~rwlock() noexcept: Destructor.

inline void rdlock(): Lock for reading.

inline void wrlock(): Lock for writing.

inline void unlock(): Unlock.

inline native_handle_type native_handle() const noexcept

Get the underlying native handle.

Returns: the underlying native handle.

thallium::rwlock_exception

class rwlock_exception : public thallium::exception : Exception class thrown by the rwlock class.

thallium::scheduler

class scheduler

Wrapper for Argobots’ ABT_scheduler.

Public Types

enum class predef : std::int32_t

Predefined scheduler types: default, basic, priority, random-work-stealing.

Values:

enumerator deflt

enumerator basic

enumerator prio

enumerator randws

enumerator basic_wait

enum class type : std::int32_t

Scheduler type.

Values:

enumerator ult

enumerator task

typedef ABT_sched native_handle_type: Underlying native handle type.

Public Functions

inline explicit scheduler(ABT_sched s)

Constructor from an ABT_sched.

Parameters: s – ABT_sched.

inline scheduler(): Builds a null scheduler.

inline native_handle_type native_handle() const

Get the underlying native handle.

Returns: the underlying native handle.

scheduler(const scheduler &other) = default: Copy constructor is deleted.

inline scheduler(scheduler &&other): Move constructor.

scheduler &operator=(const scheduler &other) = default: Copy assignment operator is deleted.

inline scheduler &operator=(scheduler &&other): Move assignment operator.

~scheduler() = default: Destructor.

inline std::size_t num_pools() const

Get the number of pools that the scheduler pulls work from.

Returns: the number of pools associated with the scheduler.

inline pool get_pool(int index) const

Get a particular pool associated with the scheduler.

Parameters: index – Index of the pool.
Returns: a pool associated with the scheduler.

inline std::size_t total_size() const

Get the sum of the sizes of the pool of sched. The size includes the blocked and migrating ULTs.

Returns: the sum of the sizes of the pool of sched.

inline std::size_t size() const

Get the sum of the sizes of the pool of sched. The size does not include the blocked and migrating ULTs.

Returns: the sum of the sizes of the pool of sched.

inline bool has_to_stop() const

Check if the scheduler needs to stop. Check if there has been an exit or a finish request and if the conditions are respected (empty pool for a finish request). If we are on the primary ES, we will jump back to the main ULT, if the scheduler has nothing to do. It is the user’s responsibility to take proper measures to stop the scheduling loop, depending on the value given by stop.

Returns: true if the scheduler has to stop.

inline void exit(): Ask a scheduler to stop as soon as possible. The scheduler will stop even if its pools are not empty. It is the user’s responsibility to ensure that the left work will be done by another scheduler.

inline void finish(): Ask a scheduler to finish. The scheduler will stop when its pools will be empty.

inline bool is_null() const noexcept

Check if the underlying scheduler handle is null.

Returns: true if the scheduler handle is null, false otherwise.

inline operator bool() const noexcept: Returns true if the scheduler handle is not null.

Public Static Functions

template<typename S, typename I> static managed<scheduler> create(const I &begin, const I &end)

Creates a scheduler based on a custom class S.

Template Parameters

S – class of scheduler implementation.
I – Iterator type for a container of pools.

Parameters

begin – Beginning iterator for the container of pools.
end – End iterator for the container of pools.

Returns

a managed<scheduler> object.

template<typename S> static managed<scheduler> create(const pool &p)

Creates a scheduler based on a custom class S.

Template Parameters

S – class implementing the scheduler.

Parameters

spd – Scheduler type.
begin – Beginning iterator for the container of pools.
end – End iterator for the container of pools.

Returns

a managed<scheduler> object.

template<typename I> static managed<scheduler> create(predef spd, const I &begin, const I &end)

Creates a scheduler based on a predefined scheduler type.

Template Parameters

I – Iterator type for a container of pools.

Parameters

spd – Scheduler type.
begin – Beginning iterator for the container of pools.
end – End iterator for the container of pools.

Returns

a managed<scheduler> object.

static inline managed<scheduler> create(predef spd, const pool &p)

Creates a scheduler based on a predefined scheduler type.

Template Parameters

I – Iterator type for a container of pools.

Parameters

spd – Scheduler type.
begin – Beginning iterator for the container of pools.
end – End iterator for the container of pools.

Returns

a managed<scheduler> object.

thallium::scheduler_exception

class scheduler_exception : public thallium::exception : Exception class thrown by the scheduler class.

thallium::self

class self

Wrapper for Argobots’ ABT_xstream_barrier.

Public Static Functions

static inline unit_type get_unit_type()

Return the type of calling work unit.

Returns: the type of calling work unit.

static inline bool is_primary()

Check if the caller is the primary ULT.

Returns: true if the caller is the primary ULT.

static inline bool on_primary_xstream()

Check if the caller’s ES is the primary ES.

Returns: true if the caller’s ES is the primary ES.

static inline int get_last_pool_id()

Get the last pool’s ID of calling work unit.

Returns: the last pool’s ID of calling work unit.

static inline void suspend(): Suspend the current ULT.

thallium::self_exception

class self_exception : public thallium::exception : Exception class thrown by the xstream_barrier class.

thallium::task

class task

The task class wraps an Argobot’s ABT_task resource. Note that the task object does NOT manage the internal ABT_task. It doesn’t do reference counting nor deletes the ABT_task when the object is destroyed. It simply provides an object-oriented interface to it. To make a task object that manages its ABT_task, use managed<task> instead.

Public Types

typedef ABT_task native_handle_type: Native handle type.

Public Functions

inline explicit task(ABT_task t)

Constructor from existing ABT_task handle.

Parameters: t – ABT_task handle.

inline task(): Default constructor.

task(const task &other) = default: Copy constructor.

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

inline task &operator=(task &&other) noexcept: Move-assignment operator. The object moved from will be invalidated if different from the object moved to.

inline task(task &&other) noexcept: Move constructor. The object moved from will be invalidated.

~task() = default: Destructor.

inline void join(): Blocks until the task terminates. Since this routine blocks, only ULTs can call this routine. If tasks use this routine, the behavior is undefined.

inline void cancel(): Request the cancelation of the target task.

inline ABT_task native_handle() const

Get the native handle of this task.

Returns: the native ABT_task handle.

inline std::uint64_t id() const

Get the id of the task.

Returns: the id of the task.

inline task_state state() const

Get the state of the task.

Returns: The state of the task.

inline void set_migratable(bool flag)

Sets the task’s migratability. By default, all tasks are migratable. If flag is true, the task becomes migratable. On the other hand, if flag is false, the target tasklet becomes unmigratable.

Parameters: flag – true to make the task migratable, false otherwise.

inline bool is_migratable() const

Returns whether the task is migratable or not.

Returns: true if the task can be migrated, false otherwise.

inline bool operator==(const task &other) const

Compares the task with another task.

Parameters: other – Task to compare against.
Returns: true if the two tasks are the same, false otherwise.

inline xstream get_xstream() const

Returns the ES associated with the task. If the target task is not associated with any ES, a null xstream is returned.

Returns: the ES associated with the task.

inline pool get_last_pool() const

If the task is not running, returns the pool where it is, else returns the last pool where it was (the pool from which the task was popped).

Returns: the last pool that had the task.

inline int get_last_pool_id() const

Get the last pool’s ID of this task.

Returns: the last pool’s ID of this task.

Public Static Functions

static inline task self()

Returns the handle of the calling task. If ULTs call this routine, a null task will be returned.

Returns: the handle to the calling task.

static inline std::uint64_t self_id()

Returns the id of the calling task. If ULTs call this routine, the result is undefined.

Returns: the id of the calling task.

thallium::task_exception

class task_exception : public thallium::exception : Exception class thrown by the task class.

thallium::thread

class thread

The thread class wraps an Argobot’s ABT_thread resource. Note that the task object does NOT manage the internal ABT_thread. It doesn’t do reference counting nor deletes the ABT_thread when the object is destroyed. It simply provides an object-oriented interface to it. To make a thread object that manages its ABT_thread, use managed<thread> instead.

Public Types

typedef ABT_thread native_handle_type: Native handle type.

Public Functions

inline thread() noexcept: Default constructor.

inline explicit thread(ABT_thread t) noexcept

Constructor from an existing ABT_thread handle.

Parameters: t – ABT_thread handle.

thread(const thread &other) = default: Copy constructor.

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

inline thread &operator=(thread &&other) noexcept: Move-assignment operator. The object moved from will be invalidated if different from the object moved to.

inline thread(thread &&other) noexcept: Move constructor. The object moved from will be invalidated.

~thread() = default: Destructor.

inline void join(): Blocks until thread terminates. Since this routine blocks, only ULTs can call this routine. If tasks use this routine, the behavior is undefined.

inline void cancel(): Request the cancelation of the thread.

inline ABT_thread native_handle() const noexcept

Returns the native handle of this thread.

Returns: the native handle of this thread.

inline std::uint64_t id() const

Get the id of this thread.

Returns: the id this thread.

inline thread_state state() const

Get the state of this thread.

Returns: the state of this thread.

inline std::size_t stacksize() const

Get the stack size of this thread.

Returns: the stack size of this thread.

inline void set_migratable(bool flag)

Sets the thread’s migratability. By default, all threads are migratable. If flag is true, the thread becomes migratable. On the other hand, if flag is false, the thread becomes unmigratable.

Parameters: flag – true to make the thread migratable, false otherwise.

inline bool is_migratable() const

Returns whether the thread is migratable or not.

Returns: true if the task can be migrated, false otherwise.

inline bool is_primary() const

confirms whether the thread, is the primary ULT.

Returns: true if the thread is the primary ULT, false otherwise.

inline bool operator==(const thread &other) const

Comparison operator for threads.

Parameters: other – Thread to compare against.
Returns: true if the two threads are equal, false otherwise.

inline void resume(): Makes the blocked ULT schedulable by changing the state of the target ULT to READY and pushing it to its associated pool. The ULT will resume its execution when the scheduler schedules it.

inline void migrate(): Requests migration of the thread but does not specify the target ES. The target ES will be determined among available ESs by the runtime.

inline void migrate_to(const xstream &es)

Requests migration of the thread to the provided ES. The actual migration occurs asynchronously with this function call. In other words, this function may return immediately without the thread being migrated. The migration request will be posted on the thread, such that next time a scheduler picks it up, migration will happen. The target pool is chosen by the running scheduler of the target ES. The migration will fail if the running scheduler has no pool available for migration.

Parameters: es – ES to migrate to.

inline void migrate_to(const scheduler &sched)

Migrate a thread to a specific scheduler.

The actual migration occurs asynchronously with this function call. In other words, this function may return immediately without the thread being migrated. The migration request will be posted on the thread, such that next time a scheduler picks it up, migration will happen. The target pool is chosen by the scheduler itself. The migration will fail if the target scheduler has no pool available for migration.

Parameters: sched – scheduler to migrate the thread to.

inline void migrate_to(const pool &p)

Migrate a thread to a specific pool.

The actual migration occurs asynchronously with this function call. In other words, this function may return immediately without the thread being migrated. The migration request will be posted on the thread, such that next time a scheduler picks it up, migration will happen.

Parameters: p – pool to migrate the thread to.

inline pool get_last_pool() const

If the thread is not running, returns the pool where it is, else returns the last pool where it was (the pool from which the thread was popped).

Returns: the last pool that had the thread.

inline int get_last_pool_id() const

Get the id of the last pool this thread belonged to.

Returns: the id of the last pool that had the thread.

Public Static Functions

static inline thread self()

Returns the handle of the calling thread. If tasks call this routine, a null thread will be returned.

Returns: the handle to the calling thread.

static inline std::uint64_t self_id()

Returns the id of the calling thread. If tasks call this routine, the result is undefined.

Returns: the id of the calling thread.

static inline void exit(): The calling ULT terminates its execution. Since the calling ULT terminates, this routine never returns.

static inline void yield(): Yield the processor from the current running ULT back to the scheduler. The ULT that yields, goes back to its pool, and eventually will be resumed automatically later.

static inline void yield_to(const thread &other)

Yield the processor from the current running thread to the specific thread. This function can be used for users to explicitly schedule the next thread to execute.

Parameters: other – thread to yield to.

static inline void sleep(const engine &eng, double ms)

Makes the current thread sleep for at least the given amount of time. The provided engine must be in an active progress loop, since it this progress loops that periodically checks for timer expiration.

Parameters

eng – engine that will check for timer expiration.
ms – time to sleep in milliseconds.

class attribute

Public Types

typedef ABT_thread_attr native_handle_type: Native handle type.

Public Functions

inline attribute(): Constructor.

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

inline attribute(attribute &&other): Move constructor.

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

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

inline ~attribute(): Destructor.

inline native_handle_type native_handle() const

Get the underlying native handle.

Returns: the native handle.

inline void set_stack(void *addr, size_t size)

Sets the address and size of the stack to use.

Parameters

addr – address of the stack.
size – size of the stack.

inline void *get_stack_address() const

Gets the address of the stack.

Returns: the address of the stack.

inline size_t get_stack_size() const

Get the size of the stack.

Returns: the size of the stack.

inline void set_migratable(bool migratable): Set the migratability of the stack.

thallium::thread_exception

class thread_exception : public thallium::exception : Exception class thrown by the thread class.

thallium::timed_callback

class timed_callback

Class returned by engine::schedule.

Public Functions

inline timed_callback &operator=(timed_callback &&other): Move-assignment operator. WARNING: do not use this method if the callback has been scheduled.

thallium::timeout

class timeout : public exception : This exception is thrown when an RPC invoked with timed() or timed_async times out.

thallium::timer

class timer

Wrapper for Argobots’ ABT_timer.

Public Types

typedef ABT_timer native_handle_type: Native handle type.

Public Functions

inline native_handle_type native_handle() const noexcept

Get the native handle.

Returns: the native handle.

inline timer(): Constructor.

inline ~timer(): Destructor.

inline timer(const timer &other): Copy constructor.

inline timer(timer &&other) noexcept: Move constructor.

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

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

inline void start(): Starts the timer.

inline void stop(): Stops the timer.

inline double read() const

Reads the current value of the timer. Returns the time difference in seconds between the start time of timer (when timer::start() was called) and the end time of timer (when timer::stop() was called).

The resolution of elapsed time is at least a unit of microsecond.

inline explicit operator double() const

See also

timer::read

Public Static Functions

static inline double wtime()

Get elapsed wall clock time.

Returns: elapsed wall clock time.

static inline double overhead()

Return the overhead of the timer class.

Returns: the overhead time when measuring the elapsed time with the timer class. It computes the time difference in consecutive calls of timer::start() and timer::stop(). The resolution of overhead time is at least a unit of microsecond.

thallium::timer_exception

class timer_exception : public thallium::exception : Exception class thrown by the timer class.

thallium::xstream

class xstream

Wrapper for Argobots’ ABT_xstream.

Public Types

typedef ABT_xstream native_handle_type: Native handle type.

Public Functions

inline explicit xstream(ABT_xstream es): Constructor from a native handle.

inline native_handle_type native_handle() const noexcept

Get the native handle.

Returns: the native handle.

inline xstream() noexcept: Default constructor. Does NOT create an ES, but a null handle.

xstream(const xstream &other) noexcept = default: Copy-constructor.

inline xstream(xstream &&other) noexcept: Move-constructor. Will invalidate the moved-from xstream instance.

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

inline xstream &operator=(xstream &&other) noexcept: Move-assignment operator.

~xstream() = default: Destructor.

inline void join()

Wait for xstream to terminate.

The xstream cannot be the same as the xstream associated with calling thread. If they are identical, this routine returns immediately without waiting for the xstream’s termination.

inline void cancel(): Request the cancelation of the target ES.

inline void revive(): Revives a joined ES.

inline int get_rank() const

Get the rank of the ES.

Returns: the rank of the ES.

inline void set_rank(int r)

Set the rank of the ES.

Parameters: r – rank to set the ES to.

inline bool is_primary() const

Check whether this ES if the primary ES.

Returns: true if the ES is the primary one, false otherwise.

inline xstream_state state() const

Get the state of the ES.

Returns: the state of the ES.

inline int get_cpubind() const

Get the id of the CPU to which this xstream is bound.

Returns: the id of the CPU to which this xstream is bound.

inline void set_cpubind(int cpuid)

Set the CPU affinity of the ES. This method binds the target ES xstream to the target CPU whose ID is cpuid. Here, the CPU ID corresponds to the processor index used by OS.

Parameters: cpuid – CPU ID

inline std::vector<int> get_affinity() const

Get the CPU affinity for the target ES in the form of a vector of CPU IDs associated with the ES.

Returns: a vector of CPU IDs.

template<typename I> inline void set_affinity(const I &begin, const I &end)

Sets the CPU affinity of the target ES by passing iterators to a set of CPU ID values.

Template Parameters

I – type of iterator.

Parameters

begin – start iterator of CPU IDs.
end – end iterator of CPU ID.

inline bool operator==(const xstream &other) const

Compares two ES.

Returns: true if the ES are the same, false otherwise.

inline bool is_null() const noexcept

Checks whether the ES is a null handle.

Returns: true if the ES is null.

inline operator bool() const noexcept

Checks whether the ES is not null.

Returns: true if the ES is not null, false otherwise.

inline void set_main_sched(const scheduler &s)

Sets the scheduler that the ES should use.

Parameters: s – Scheduler that the ES should use.

template<typename I> inline void set_main_sched(const scheduler::predef &s, const I &begin, const I &end)

Sets the scheduler that the ES schould use, using a scheduler predefinition and a set of pools that this scheduler should use.

Template Parameters

I – type of iterator for the container of pools.

Parameters

s – scheduler predefinition.
begin – starting iterator of the list of pools.
end – end iterator of the list of pools.

inline scheduler get_main_sched() const

Get the main scheduler used by the xstream.

Returns: the main scheduler used by the xstream.

inline std::vector<pool> get_main_pools(int max_pools = -1) const

Get up to max_pools pools associated with the ES’s scheduler. If max_pools is not provided, this method retrieves all the pools.

Parameters: max_pools – maximum number of pools to retrieve.
Returns: a vector of pools associated with the ES.

template<typename F> managed<thread> make_thread(F &&f)

Create a thread running the specified function and push it into the pool.

Template Parameters: F – type of function to run as a thread. Must have operator()().
Parameters: f – Function to run as a thread.
Returns: a managed<thread> object managing the created thread.

template<typename F, typename Attr> managed<thread> make_thread(F &&f, const Attr &attr)

Create a thread running the specified function and push it into the pool.

Template Parameters

F – type of function to run as a thread. Must have operator()().

Parameters

f – Function to run as a thread.
attr – Thread attributes.

Returns

a managed<thread> object managing the created thread.

template<typename F> managed<task> make_task(F &&f)

Create a task running the specified function and push it into the pool.

Template Parameters: F – type of function to run as a task. Must have operator()().
Parameters: f – Function to run as a task.
Returns: a managed<task> object managing the create task.

inline void reset_scheduler_to_default()

This function detaches any scheduler attached to the ES and makes the ES use a default scheduler with a default pool.

This function should generally be used on the primary ES to detach a scheduler that has been installed by the user and that the user is managing using a managed<> construct, before such a managed scheduler goes out of scope.

Public Static Functions

static inline managed<xstream> create()

Creates a managed xstream object with a default scheduler and private pool.

Returns: a managed<xstream> object.

static inline managed<xstream> create(scheduler::predef spd, const pool &p)

Creates a managed xstream with a predefined scheduler and a given pool.

Parameters

spd – predefined scheduler type.
p – pool for the ES’s scheduler to use.

Returns

a managed<xstream> object.

template<typename I> static inline managed<xstream> create(scheduler::predef spd, const I &begin, const I &end)

Creates an xstream with a predefined scheduler and a set of pools.

Template Parameters

I – Type of iterator of the container that contains the pools.

Parameters

spd – scheduler predefinition
begin – beginning iterator for the set of pools to use
end – end iterator for the set of pools to use

Returns

a managed<xstream> object.

static inline managed<xstream> create(const scheduler &sched)

Creates a managed xstream using the provided scheduler.

Parameters: sched – Scheduler that the xstream should use.
Returns: a managed<xstream> object.

static inline managed<xstream> create(const scheduler &sched, int rank)

Creates a managed xstream using the provided scheduler, and assign it the given rank.

Parameters

sched – Scheduler to be used by the xstream.
rank – rank of the ES.

Returns

a managed<xstream> object.

static inline void exit(): Terminate the ES associated with the calling ULT.

static inline xstream self()

Return the ES handle associated with the caller work unit.

Returns: the ES handle associated with the caller work unit.

static inline int self_rank()

Return the rank of the ES associated with the caller work unit.

Returns: the rank of the ES associated with the caller work unit.

static inline int num()

Returns the number of running ES.

Returns: the number of running ES.

static inline void check_events(const scheduler &s)

Check the events and process them.

This function must be called by a scheduler periodically. Therefore, a user will use it on his own defined scheduler.

Parameters: s – scheduler requesting to check for events.

thallium::xstream_barrier

class xstream_barrier

Wrapper for Argobots’ ABT_xstream_barrier.

Public Types

typedef ABT_xstream_barrier native_handle_type: Native handle type (ABT_xstream_barrier)

Public Functions

inline explicit xstream_barrier(uint32_t num_waiters)

Constructor.

Parameters: num_waiters – Number of waiters.

xstream_barrier(const xstream_barrier &other) = delete: Copy constructor is deleted.

xstream_barrier &operator=(const xstream_barrier &other) = delete: Copy assignment operator is deleted.

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

Move assignment operator.

If the right and left operands are different, this method will free the left operand’s resource (if necessary), and assign it the right operand’s resource. The right operand will be invalidated.

inline xstream_barrier(xstream_barrier &&other)

Move constructor. The right operand will be invalidated.

Parameters: other – barrier object to move from.

inline ~xstream_barrier(): Destructor.

inline void wait(): Waits on the barrier.

inline native_handle_type native_handle() const noexcept

Get the underlying ABT_xstream_barrier handle.

Returns: the underlying ABT_xstream_barrier handle.

thallium::xstream_barrier_exception

class xstream_barrier_exception : public thallium::exception : Exception class thrown by the xstream_barrier class.

thallium::xstream_exception

class xstream_exception : public thallium::exception : Exception class thrown by the task class.