coroutines

The contents of this module can be included with the header hpx/modules/coroutines.hpp. These headers may be used by user-code but are not guaranteed stable (neither header location nor contents). You are using these at your own risk. If you wish to use non-public functionality from a module we strongly suggest only including the module header hpx/modules/coroutines.hpp, not the particular header in which the functionality you would like to use is defined. See Public API for a list of names that are part of the public HPX API.

namespace hpx
namespace threads
namespace coroutines
class coroutine

Public Types

using impl_type = detail::coroutine_impl
using thread_id_type = impl_type::thread_id_type
using result_type = impl_type::result_type
using arg_type = impl_type::arg_type
using functor_type = util::unique_function_nonser<result_type(arg_type)>

Public Functions

coroutine(functor_type &&f, thread_id_type id, std::ptrdiff_t stack_size = detail::default_stack_size)
coroutine(coroutine const &src)
coroutine &operator=(coroutine const &src)
coroutine(coroutine &&src)
coroutine &operator=(coroutine &&src)
thread_id_type get_thread_id() const
std::size_t get_thread_data() const
std::size_t set_thread_data(std::size_t data)
void init()
void rebind(functor_type &&f, thread_id_type id)
result_type operator()(arg_type arg = arg_type())
bool is_ready() const
std::ptrdiff_t get_available_stack_space()
impl_type *impl()

Private Members

impl_type impl_
namespace hpx
namespace threads
namespace coroutines
class stackless_coroutine

Public Types

using thread_id_type = hpx::threads::thread_id
using result_type = std::pair<thread_schedule_state, thread_id_type>
using arg_type = thread_restart_state
using functor_type = util::unique_function_nonser<result_type(arg_type)>

Public Functions

stackless_coroutine(functor_type &&f, thread_id_type id, std::ptrdiff_t = default_stack_size)
~stackless_coroutine()
stackless_coroutine(stackless_coroutine const &src)
stackless_coroutine &operator=(stackless_coroutine const &src)
stackless_coroutine(stackless_coroutine &&src)
stackless_coroutine &operator=(stackless_coroutine &&src)
thread_id_type get_thread_id() const
std::size_t get_thread_data() const
std::size_t set_thread_data(std::size_t data)
void rebind(functor_type &&f, thread_id_type id)
void reset_tss()
void reset()
stackless_coroutine::result_type operator()(arg_type arg = arg_type())
operator bool() const
bool is_ready() const
std::ptrdiff_t get_available_stack_space()
std::size_t &get_continuation_recursion_count()

Protected Attributes

functor_type f_
context_state state_
thread_id_type id_
std::size_t thread_data_
std::size_t continuation_recursion_count_

Private Types

enum context_state

Values:

ctx_running
ctx_ready
ctx_exited

Private Functions

bool running() const
bool exited() const

Private Static Attributes

constexpr std::ptrdiff_t default_stack_size = -1

Friends

friend hpx::threads::coroutines::reset_on_exit
struct reset_on_exit

Public Functions

reset_on_exit(stackless_coroutine &this__)
~reset_on_exit()

Public Members

stackless_coroutine &this_

Defines

HPX_THREAD_STATE_UNSCOPED_ENUM_DEPRECATION_MSG
HPX_THREAD_PRIORITY_UNSCOPED_ENUM_DEPRECATION_MSG
HPX_THREAD_STATE_EX_UNSCOPED_ENUM_DEPRECATION_MSG
HPX_THREAD_STACKSIZE_UNSCOPED_ENUM_DEPRECATION_MSG
HPX_THREAD_SCHEDULE_HINT_UNSCOPED_ENUM_DEPRECATION_MSG
namespace hpx
namespace threads

Enums

enum thread_schedule_state

The thread_schedule_state enumerator encodes the current state of a thread instance

Values:

unknown = 0
active = 1

thread is currently active (running, has resources)

pending = 2

thread is pending (ready to run, but no hardware resource available)

suspended = 3

thread has been suspended (waiting for synchronization event, but still known and under control of the thread-manager)

depleted = 4

thread has been depleted (deeply suspended, it is not known to the thread-manager)

terminated = 5

thread has been stopped an may be garbage collected

staged = 6

this is not a real thread state, but allows to reference staged task descriptions, which eventually will be converted into thread objects

pending_do_not_schedule = 7
pending_boost = 8
enum thread_priority

This enumeration lists all possible thread-priorities for HPX threads.

Values:

unknown = -1
default_ = 0

Will assign the priority of the task to the default (normal) priority.

low = 1

Task goes onto a special low priority queue and will not be executed until all high/normal priority tasks are done, even if they are added after the low priority task.

normal = 2

Task will be executed when it is taken from the normal priority queue, this is usually a first in-first-out ordering of tasks (depending on scheduler choice). This is the default priority.

high_recursive = 3

The task is a high priority task and any child tasks spawned by this task will be made high priority as well - unless they are specifically flagged as non default priority.

boost = 4

Same as thread_priority_high except that the thread will fall back to thread_priority_normal if resumed after being suspended.

high = 5

Task goes onto a special high priority queue and will be executed before normal/low priority tasks are taken (some schedulers modify the behavior slightly and the documentation for those should be consulted).

bound = 6

Task goes onto a special high priority queue and will never be stolen by another thread after initial assignment. This should be used for thread placement tasks such as OpenMP type for loops.

enum thread_restart_state

The thread_restart_state enumerator encodes the reason why a thread is being restarted

Values:

unknown = 0
signaled = 1

The thread has been signaled.

timeout = 2

The thread has been reactivated after a timeout

terminate = 3

The thread needs to be terminated.

abort = 4

The thread needs to be aborted.

enum thread_stacksize

A thread_stacksize references any of the possible stack-sizes for HPX threads.

Values:

unknown = -1
small_ = 1

use small stack size (the underscore is to work around small being defined to char on Windows)

medium = 2

use medium sized stack size

large = 3

use large stack size

huge = 4

use very large stack size

nostack = 5

this thread does not suspend (does not need a stack)

current = 6

use size of current thread’s stack

default_ = small_

use default stack size

minimal = small_

use minimally stack size

maximal = huge

use maximally stack size

enum thread_schedule_hint_mode

The type of hint given when creating new tasks.

Values:

none = 0

A hint that leaves the choice of scheduling entirely up to the scheduler.

thread = 1

A hint that tells the scheduler to prefer scheduling a task on the local thread number associated with this hint. Local thread numbers are indexed from zero. It is up to the scheduler to decide how to interpret thread numbers that are larger than the number of threads available to the scheduler. Typically thread numbers will wrap around when too large.

numa = 2

A hint that tells the scheduler to prefer scheduling a task on the NUMA domain associated with this hint. NUMA domains are indexed from zero. It is up to the scheduler to decide how to interpret NUMA domain indices that are larger than the number of available NUMA domains to the scheduler. Typically indices will wrap around when too large.

Functions

std::ostream &operator<<(std::ostream &os, thread_schedule_state const t)
char const *get_thread_state_name(thread_schedule_state state)

Returns the name of the given state.

Get the readable string representing the name of the given thread_state constant.

Parameters
  • state: this represents the thread state.

std::ostream &operator<<(std::ostream &os, thread_priority const t)
char const *get_thread_priority_name(thread_priority priority)

Return the thread priority name.

Get the readable string representing the name of the given thread_priority constant.

Parameters
  • this: represents the thread priority.

std::ostream &operator<<(std::ostream &os, thread_restart_state const t)
char const *get_thread_state_ex_name(thread_restart_state state)

Get the readable string representing the name of the given thread_restart_state constant.

char const *get_thread_state_name(thread_state state)

Get the readable string representing the name of the given thread_state constant.

std::ostream &operator<<(std::ostream &os, thread_stacksize const t)
char const *get_stack_size_enum_name(thread_stacksize size)

Returns the stack size name.

Get the readable string representing the given stack size constant.

Parameters
  • size: this represents the stack size

hpx::threads::HPX_DEPRECATED_V(1, 6, HPX_THREAD_SCHEDULE_HINT_UNSCOPED_ENUM_DEPRECATION_MSG) const

Variables

constexpr thread_schedule_state unknown = thread_schedule_state::unknown
constexpr thread_schedule_state active = thread_schedule_state::active
constexpr thread_schedule_state pending = thread_schedule_state::pending
constexpr thread_schedule_state suspended = thread_schedule_state::suspended
constexpr thread_schedule_state depleted = thread_schedule_state::depleted
constexpr thread_schedule_state terminated = thread_schedule_state::terminated
constexpr thread_schedule_state staged = thread_schedule_state::staged
constexpr thread_schedule_state pending_do_not_schedule = thread_schedule_state::pending_do_not_schedule
constexpr thread_schedule_state pending_boost = thread_schedule_state::pending_boost
constexpr thread_priority thread_priority_unknown = thread_priority::unknown
constexpr thread_priority thread_priority_default = thread_priority::default_
constexpr thread_priority thread_priority_low = thread_priority::low
constexpr thread_priority thread_priority_normal = thread_priority::normal
constexpr thread_priority thread_priority_high_recursive = thread_priority::high_recursive
constexpr thread_priority thread_priority_boost = thread_priority::boost
constexpr thread_priority thread_priority_high = thread_priority::high
constexpr thread_priority thread_priority_bound = thread_priority::bound
constexpr thread_priority thread_priority_critical = thread_priority::critical
constexpr thread_restart_state wait_unknown = thread_restart_state::unknown
constexpr thread_restart_state wait_signaled = thread_restart_state::signaled
constexpr thread_restart_state wait_timeout = thread_restart_state::timeout
constexpr thread_restart_state wait_terminate = thread_restart_state::terminate
constexpr thread_restart_state wait_abort = thread_restart_state::abort
constexpr thread_stacksize thread_stacksize_unknown = thread_stacksize::unknown
constexpr thread_stacksize thread_stacksize_small = thread_stacksize::small_
constexpr thread_stacksize thread_stacksize_medium = thread_stacksize::medium
constexpr thread_stacksize thread_stacksize_large = thread_stacksize::large
constexpr thread_stacksize thread_stacksize_huge = thread_stacksize::huge
constexpr thread_stacksize thread_stacksize_nostack = thread_stacksize::nostack
constexpr thread_stacksize thread_stacksize_current = thread_stacksize::current
constexpr thread_stacksize thread_stacksize_default = thread_stacksize::default_
constexpr thread_stacksize thread_stacksize_minimal = thread_stacksize::minimal
constexpr thread_stacksize thread_stacksize_maximal = thread_stacksize::maximal
struct thread_schedule_hint
#include <thread_enums.hpp>

A hint given to a scheduler to guide where a task should be scheduled.

A scheduler is free to ignore the hint, or modify the hint to suit the resources available to the scheduler.

Public Functions

constexpr thread_schedule_hint()

Construct a default hint with mode thread_schedule_hint_mode::none.

constexpr thread_schedule_hint(std::int16_t thread_hint)

Construct a hint with mode thread_schedule_hint_mode::thread and the given hint as the local thread number.

constexpr thread_schedule_hint(thread_schedule_hint_mode mode, std::int16_t hint)

Construct a hint with the given mode and hint. The numerical hint is unused when the mode is thread_schedule_hint_mode::none.

Public Members

std::int16_t hint

The hint associated with the mode. The interepretation of this hint depends on the given mode.

thread_schedule_hint_mode mode

The mode of the scheduling hint.

template<>
struct hash<::hpx::threads::thread_id>

Public Functions

std::size_t operator()(::hpx::threads::thread_id const &v) const
template<>
struct hash<::hpx::threads::thread_id_ref>

Public Functions

std::size_t operator()(::hpx::threads::thread_id_ref const &v) const
namespace hpx
namespace threads

Enums

enum thread_id_addref

Values:

yes
no

Variables

constexpr const thread_id invalid_thread_id
struct thread_id

Public Functions

thread_id()
thread_id(thread_id const&)
thread_id &operator=(thread_id const&)
constexpr thread_id(thread_id &&rhs)
constexpr thread_id &operator=(thread_id &&rhs)
constexpr thread_id(thread_id_repr const &thrd)
constexpr thread_id &operator=(thread_id_repr const &rhs)
constexpr operator bool() const
constexpr thread_id_repr get() const
constexpr void reset()

Private Types

using thread_id_repr = void*

Private Members

thread_id_repr thrd_ = nullptr

Friends

friend constexpr bool operator==(std::nullptr_t, thread_id const &rhs)
friend constexpr bool operator!=(std::nullptr_t, thread_id const &rhs)
friend constexpr bool operator==(thread_id const &lhs, std::nullptr_t)
friend constexpr bool operator!=(thread_id const &lhs, std::nullptr_t)
friend constexpr bool operator==(thread_id const &lhs, thread_id const &rhs)
friend constexpr bool operator!=(thread_id const &lhs, thread_id const &rhs)
friend constexpr bool operator<(thread_id const &lhs, thread_id const &rhs)
friend constexpr bool operator>(thread_id const &lhs, thread_id const &rhs)
friend constexpr bool operator<=(thread_id const &lhs, thread_id const &rhs)
friend constexpr bool operator>=(thread_id const &lhs, thread_id const &rhs)
template<typename Char, typename Traits>
std::basic_ostream<Char, Traits> &operator<<(std::basic_ostream<Char, Traits> &os, thread_id const &id)
void format_value(std::ostream &os, boost::string_ref spec, thread_id const &id)
struct thread_id_ref

Public Types

using thread_repr = detail::thread_data_reference_counting

Public Functions

thread_id_ref()
thread_id_ref(thread_id_ref const&)
thread_id_ref &operator=(thread_id_ref const&)
thread_id_ref(thread_id_ref &&rhs)
thread_id_ref &operator=(thread_id_ref &&rhs)
thread_id_ref(thread_id_repr const &thrd)
thread_id_ref(thread_id_repr &&thrd)
thread_id_ref &operator=(thread_id_repr const &rhs)
thread_id_ref &operator=(thread_id_repr &&rhs)
thread_id_ref(thread_repr *thrd, thread_id_addref addref = thread_id_addref::yes)
thread_id_ref &operator=(thread_repr *rhs)
thread_id_ref(thread_id const &noref)
thread_id_ref(thread_id &&noref)
thread_id_ref &operator=(thread_id const &noref)
thread_id_ref &operator=(thread_id &&noref)
operator bool() const
thread_id noref() const
thread_id_repr &get() &
thread_id_repr &&get() &&
thread_id_repr const &get() const &
void reset()
void reset(thread_repr *thrd, bool add_ref = true)
constexpr thread_repr *detach()

Private Types

using thread_id_repr = hpx::intrusive_ptr<detail::thread_data_reference_counting>

Private Members

thread_id_repr thrd_

Friends

bool operator==(std::nullptr_t, thread_id_ref const &rhs)
bool operator!=(std::nullptr_t, thread_id_ref const &rhs)
bool operator==(thread_id_ref const &lhs, std::nullptr_t)
bool operator!=(thread_id_ref const &lhs, std::nullptr_t)
bool operator==(thread_id_ref const &lhs, thread_id_ref const &rhs)
bool operator!=(thread_id_ref const &lhs, thread_id_ref const &rhs)
bool operator<(thread_id_ref const &lhs, thread_id_ref const &rhs)
bool operator>(thread_id_ref const &lhs, thread_id_ref const &rhs)
bool operator<=(thread_id_ref const &lhs, thread_id_ref const &rhs)
bool operator>=(thread_id_ref const &lhs, thread_id_ref const &rhs)
template<typename Char, typename Traits>
std::basic_ostream<Char, Traits> &operator<<(std::basic_ostream<Char, Traits> &os, thread_id_ref const &id)
void format_value(std::ostream &os, boost::string_ref spec, thread_id_ref const &id)
namespace std
template<>
struct hash<::hpx::threads::thread_id>

Public Functions

std::size_t operator()(::hpx::threads::thread_id const &v) const
template<>
struct hash<::hpx::threads::thread_id_ref>

Public Functions

std::size_t operator()(::hpx::threads::thread_id_ref const &v) const