API Documentation
thallium::abt_exception
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.
-
async_response(const async_response &other) = delete
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.
-
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.
-
typedef ABT_barrier native_handle_type
thallium::barrier_exception
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() 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
-
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.
-
inline bulk() noexcept
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
-
inline bulk_segment(const bulk &b) noexcept
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.
-
inline callable_remote_procedure_with_context(const callable_remote_procedure_with_context &other)
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
-
typedef ABT_cond native_handle_type
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 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 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.
-
inline endpoint(const engine &e, hg_addr_t addr, bool take_ownership = true)
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(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()
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.
-
engine() = default
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.
-
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 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.
-
using value_type = typename std::remove_reference<typename std::remove_cv<T>::type>::type
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
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.
-
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
-
inline void set(T *value)
Set one of the future’s values.
- Parameters
value – pointer to the value to set.
-
inline ~future()
Destructor.
-
typedef ABT_future native_handle_type
thallium::future_exception
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
-
inline ~managed()
Destructor.
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.
-
inline margo_exception(const std::string &function, const std::string file, unsigned line, hg_return_t ret, const std::string &message = std::string())
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.
-
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.
-
typedef ABT_mutex native_handle_type
thallium::mutex_exception
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.
-
inline hg_handle_t native_handle() const
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
-
enumerator priv
-
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() = 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.
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).
-
enum class access : std::int32_t
thallium::pool_exception
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.
-
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.
-
inline proc_input_archive(hg_proc_t p, std::tuple<CtxArg...> &context, const std::weak_ptr<detail::engine_impl> &e)
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.
-
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.
-
inline proc_output_archive(hg_proc_t p, std::tuple<CtxArg...> &context, std::weak_ptr<detail::engine_impl> e)
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 –
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 provider_handle(const engine &e, hg_addr_t addr, uint16_t provider_id = 0, bool take_ownership = true)
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.
-
inline recursive_mutex()
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(const remote_bulk&) = default
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.
-
remote_procedure(const remote_procedure &other) = default
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 request_with_context(const request_with_context &other)
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.
-
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.
-
typedef ABT_rwlock native_handle_type
thallium::rwlock_exception
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
-
enumerator deflt
-
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() = 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.
-
enum class predef : std::int32_t
thallium::scheduler_exception
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.
-
static inline unit_type get_unit_type()
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.
-
inline task &operator=(task &&other) noexcept
Move-assignment operator. The object moved from will be invalidated if different from the object moved to.
-
~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.
-
typedef ABT_task native_handle_type
thallium::task_exception
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.
-
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.
-
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.
-
typedef ABT_thread_attr native_handle_type
-
typedef ABT_thread native_handle_type
thallium::thread_exception
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.
-
inline timed_callback &operator=(timed_callback &&other)
thallium::timeout
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 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
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.
-
typedef ABT_timer native_handle_type
thallium::timer_exception
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.
-
inline xstream(xstream &&other) noexcept
Move-constructor. Will invalidate the moved-from xstream instance.
-
~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.
-
typedef ABT_xstream native_handle_type
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.
-
typedef ABT_xstream_barrier native_handle_type
thallium::xstream_barrier_exception
-
class xstream_barrier_exception : public thallium::exception
Exception class thrown by the xstream_barrier class.