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 engine get_engine() const

Returns the engine that created this endpoint.

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 void release()

Release the underlying resource. This is equivalent to doing m = tl::managed<T>{};.

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.

template<typename ...T>
inline void unpack(T&... x) const

Unpack the data into a provided set of arguments. This function is preferable to as<T> or to casting into the resulting type in cases where the resulting type cannot be easily moved, or the caller already has an instance of it that needs to be set.

Template Parameters

T – Types into which to unpack.

Parameters

x – Objects into which to unpack.

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 const char *identity() const

Returns the identity of the provider.

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.

inline std::string get_identity() const

Send an RPC to get the identity of the remote provider.

Returns

The identity as a string.

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.

Subclassed by thallium::auto_remote_procedure

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.