hpx/coroutines/thread_enums.hpp#

Defined in header hpx/coroutines/thread_enums.hpp.

See Public API for a list of names and headers that are part of the public HPX API.

namespace hpx
namespace threads#

Enums

enum class thread_schedule_state : std::int8_t#

The thread_schedule_state enumerator encodes the current state of a thread instance

Values:

enumerator unknown#
enumerator active#

thread is currently active (running, has resources)

enumerator pending#

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

enumerator suspended#

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

enumerator depleted#

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

enumerator terminated#

thread has been stopped an may be garbage collected

enumerator staged#

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

enumerator pending_do_not_schedule#

this is not a real thread state, but allows to create a thread in pending state without scheduling it (internal, do not use)

enumerator pending_boost#

this is not a real thread state, but allows to suspend a thread in pending state without high priority rescheduling

enumerator deleted#

thread has been stopped and was deleted

enum class thread_priority : std::int8_t#

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

Values:

enumerator unknown#
enumerator default_#

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

enumerator low#

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.

enumerator normal#

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.

enumerator high_recursive#

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.

enumerator boost#

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

enumerator high#

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).

enumerator bound#

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 class thread_restart_state : std::int8_t#

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

Values:

enumerator unknown#
enumerator signaled#

The thread has been signaled.

enumerator timeout#

The thread has been reactivated after a timeout.

enumerator terminate#

The thread needs to be terminated.

enumerator abort#

The thread needs to be aborted.

enum class thread_stacksize : std::int8_t#

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

Values:

enumerator unknown#
enumerator small_#

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

enumerator medium#

use medium sized stack size

enumerator large#

use large stack size

enumerator huge#

use very large stack size

enumerator nostack#

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

enumerator current#

use size of current thread’s stack

enumerator default_#

use default stack size

enumerator minimal#

use minimally stack size

enumerator maximal#

use maximally stack size

enum class thread_schedule_hint_mode : std::int8_t#

The type of hint given when creating new tasks.

Values:

enumerator none#

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

enumerator thread#

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.

enumerator numa#

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.

enum class thread_placement_hint : std::int8_t#

The type of hint given to the scheduler related to thread placement

The type of hint given to the scheduler related running a thread as a child directly in the context of the parent thread

Values:

enumerator none#

No hint is specified. The implementation is free to chose what placement methods to use.

enumerator depth_first#

A hint that tells the scheduler to prefer spreading thread placement on a depth-first basis (i.e. consecutively scheduled threads are placed on the same core).

enumerator breadth_first#

A hint that tells the scheduler to prefer spreading thread placement on a breadth-first basis (i.e. consecutively scheduled threads are placed on the neighboring cores).

enumerator depth_first_reverse#

A hint that tells the scheduler to prefer spreading thread placement on a depth-first basis (i.e. consecutively scheduled threads are placed on the same core). Threads are being scheduled in reverse order.

enumerator breadth_first_reverse#

A hint that tells the scheduler to prefer spreading thread placement on a breadth-first basis (i.e. consecutively scheduled threads are placed on the neighboring cores). Threads are being scheduled in reverse order.

enum class thread_sharing_hint : std::int8_t#

The type of hint given to the scheduler related to whether it is ok to share the invoked function object between threads

Values:

enumerator none#

No hint is specified. The implementation is free to chose what sharing methods to use.

enumerator do_not_share_function#

A hint that tells the scheduler to avoid sharing the given function (object) between threads.

enumerator do_not_combine_tasks#

A hint that tells the scheduler to avoid combining tasks on the same thread. This is important for tasks that may synchronize between each other, which could lead to deadlocks if those tasks are combined running by the same thread.

enum class thread_execution_hint : std::int8_t#

Values:

enumerator none#

No hint is specified. Always run the thread in its own execution environment.

enumerator run_as_child#

Attempt to run the thread in the execution context of the parent thread.

Functions

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

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 t)#
char const *get_thread_priority_name(thread_priority priority) noexcept#

Return the thread priority name.

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

Parameters

priority – this represents the thread priority.

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

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

char const *get_thread_state_name(thread_state state) noexcept#

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

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

Returns the stack size name.

Get the readable string representing the given stack size constant.

Parameters

size – this represents the stack size

constexpr bool do_not_share_function(thread_sharing_hint hint) noexcept#
constexpr bool do_not_combine_tasks(thread_sharing_hint hint) noexcept#
constexpr thread_sharing_hint operator|(thread_sharing_hint lhs, thread_sharing_hint rhs) noexcept#
constexpr bool run_as_child(thread_execution_hint hint) noexcept#

Variables

constexpr thread_execution_hint default_runs_as_child_hint = thread_execution_hint::none#

Default value to use for runs-as-child mode (if true, then futures will attempt to execute associated threads directly if they have not started running).

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

inline constexpr thread_schedule_hint() noexcept#

Construct a default hint with mode thread_schedule_hint_mode::none.

inline explicit constexpr thread_schedule_hint(std::int16_t thread_hint, thread_placement_hint placement = thread_placement_hint::none, thread_execution_hint runs_as_child = default_runs_as_child_hint, thread_sharing_hint sharing = thread_sharing_hint::none) noexcept#

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

inline constexpr thread_schedule_hint(thread_schedule_hint_mode mode, std::int16_t hint, thread_placement_hint placement = thread_placement_hint::none, thread_execution_hint runs_as_child = default_runs_as_child_hint, thread_sharing_hint sharing = thread_sharing_hint::none) noexcept#

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

inline constexpr thread_placement_hint placement_mode() const noexcept#
inline void placement_mode(thread_placement_hint bits) noexcept#
inline constexpr thread_sharing_hint sharing_mode() const noexcept#
inline void sharing_mode(thread_sharing_hint bits) noexcept#
inline constexpr thread_execution_hint runs_as_child_mode() const noexcept#
inline void runs_as_child_mode(thread_execution_hint bits) noexcept#

Public Members

std::int16_t hint = -1#

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

thread_schedule_hint_mode mode = thread_schedule_hint_mode::none#

The mode of the scheduling hint.

std::uint8_t placement_mode_bits#

The mode of the desired thread placement.

std::uint8_t sharing_mode_bits#

The mode of the desired sharing hint.

std::uint8_t runs_as_child_mode_bits#

The thread will run as a child directly in the context of the current thread