hpx/threading_base/thread_helpers.hpp¶
See Public API for a list of names and headers that are part of the public HPX API.
-
namespace
hpx
-
namespace
this_thread
Functions
-
threads::thread_restart_state
suspend
(threads::thread_schedule_state state, threads::thread_id_type id, util::thread_description const &description = util::thread_description("this_thread::suspend"), error_code &ec = throws)¶ The function suspend will return control to the thread manager (suspends the current thread). It sets the new state of this thread to the thread state passed as the parameter.
- Note
Must be called from within a HPX-thread.
- Exceptions
If
:&ec != &throws
, never throws, but will set ec to an appropriate value when an error occurs. Otherwise, this function will throw an hpx::exception with an error code of hpx::yield_aborted if it is signaled with wait_aborted. If called outside of a HPX-thread, this function will throw an hpx::exception with an error code of hpx::null_thread_id. If this function is called while the thread-manager is not running, it will throw an hpx::exception with an error code of hpx::invalid_status.
-
threads::thread_restart_state
suspend
(threads::thread_schedule_state state = threads::thread_schedule_state::pending, util::thread_description const &description = util::thread_description("this_thread::suspend"), error_code &ec = throws)¶ The function suspend will return control to the thread manager (suspends the current thread). It sets the new state of this thread to the thread state passed as the parameter.
- Note
Must be called from within a HPX-thread.
- Exceptions
If
:&ec != &throws
, never throws, but will set ec to an appropriate value when an error occurs. Otherwise, this function will throw an hpx::exception with an error code of hpx::yield_aborted if it is signaled with wait_aborted. If called outside of a HPX-thread, this function will throw an hpx::exception with an error code of hpx::null_thread_id. If this function is called while the thread-manager is not running, it will throw an hpx::exception with an error code of hpx::invalid_status.
-
threads::thread_restart_state
suspend
(hpx::chrono::steady_time_point const &abs_time, threads::thread_id_type id, util::thread_description const &description = util::thread_description("this_thread::suspend"), error_code &ec = throws)¶ The function suspend will return control to the thread manager (suspends the current thread). It sets the new state of this thread to suspended and schedules a wakeup for this threads at the given time.
- Note
Must be called from within a HPX-thread.
- Exceptions
If
:&ec != &throws
, never throws, but will set ec to an appropriate value when an error occurs. Otherwise, this function will throw an hpx::exception with an error code of hpx::yield_aborted if it is signaled with wait_aborted. If called outside of a HPX-thread, this function will throw an hpx::exception with an error code of hpx::null_thread_id. If this function is called while the thread-manager is not running, it will throw an hpx::exception with an error code of hpx::invalid_status.
-
threads::thread_restart_state
suspend
(hpx::chrono::steady_time_point const &abs_time, util::thread_description const &description = util::thread_description("this_thread::suspend"), error_code &ec = throws)¶ The function suspend will return control to the thread manager (suspends the current thread). It sets the new state of this thread to suspended and schedules a wakeup for this threads at the given time.
- Note
Must be called from within a HPX-thread.
- Exceptions
If
:&ec != &throws
, never throws, but will set ec to an appropriate value when an error occurs. Otherwise, this function will throw an hpx::exception with an error code of hpx::yield_aborted if it is signaled with wait_aborted. If called outside of a HPX-thread, this function will throw an hpx::exception with an error code of hpx::null_thread_id. If this function is called while the thread-manager is not running, it will throw an hpx::exception with an error code of hpx::invalid_status.
-
threads::thread_restart_state
suspend
(hpx::chrono::steady_duration const &rel_time, util::thread_description const &description = util::thread_description("this_thread::suspend"), error_code &ec = throws)¶ The function suspend will return control to the thread manager (suspends the current thread). It sets the new state of this thread to suspended and schedules a wakeup for this threads after the given duration.
- Note
Must be called from within a HPX-thread.
- Exceptions
If
:&ec != &throws
, never throws, but will set ec to an appropriate value when an error occurs. Otherwise, this function will throw an hpx::exception with an error code of hpx::yield_aborted if it is signaled with wait_aborted. If called outside of a HPX-thread, this function will throw an hpx::exception with an error code of hpx::null_thread_id. If this function is called while the thread-manager is not running, it will throw an hpx::exception with an error code of hpx::invalid_status.
-
threads::thread_restart_state
suspend
(hpx::chrono::steady_duration const &rel_time, threads::thread_id_type const &id, util::thread_description const &description = util::thread_description("this_thread::suspend"), error_code &ec = throws)¶ The function suspend will return control to the thread manager (suspends the current thread). It sets the new state of this thread to suspended and schedules a wakeup for this threads after the given duration.
- Note
Must be called from within a HPX-thread.
- Exceptions
If
:&ec != &throws
, never throws, but will set ec to an appropriate value when an error occurs. Otherwise, this function will throw an hpx::exception with an error code of hpx::yield_aborted if it is signaled with wait_aborted. If called outside of a HPX-thread, this function will throw an hpx::exception with an error code of hpx::null_thread_id. If this function is called while the thread-manager is not running, it will throw an hpx::exception with an error code of hpx::invalid_status.
-
threads::thread_restart_state
suspend
(std::uint64_t ms, util::thread_description const &description = util::thread_description("this_thread::suspend"), error_code &ec = throws)¶ The function suspend will return control to the thread manager (suspends the current thread). It sets the new state of this thread to suspended and schedules a wakeup for this threads after the given time (specified in milliseconds).
- Note
Must be called from within a HPX-thread.
- Exceptions
If
:&ec != &throws
, never throws, but will set ec to an appropriate value when an error occurs. Otherwise, this function will throw an hpx::exception with an error code of hpx::yield_aborted if it is signaled with wait_aborted. If called outside of a HPX-thread, this function will throw an hpx::exception with an error code of hpx::null_thread_id. If this function is called while the thread-manager is not running, it will throw an hpx::exception with an error code of hpx::invalid_status.
-
threads::thread_pool_base *
get_pool
(error_code &ec = throws)¶ Returns a pointer to the pool that was used to run the current thread
- Exceptions
If
:&ec != &throws
, never throws, but will set ec to an appropriate value when an error occurs. Otherwise, this function will throw an hpx::exception with an error code of hpx::yield_aborted if it is signaled with wait_aborted. If called outside of a HPX-thread, this function will throw an hpx::exception with an error code of hpx::null_thread_id. If this function is called while the thread-manager is not running, it will throw an hpx::exception with an error code of hpx::invalid_status.
-
threads::thread_restart_state
-
namespace
threads
Functions
-
thread_state
set_thread_state
(thread_id_type const &id, thread_schedule_state state = thread_schedule_state::pending, thread_restart_state stateex = thread_restart_state::signaled, thread_priority priority = thread_priority::normal, bool retry_on_active = true, hpx::error_code &ec = throws)¶ Set the thread state of the thread referenced by the thread_id id.
- Note
If the thread referenced by the parameter id is in thread_state::active state this function schedules a new thread which will set the state of the thread as soon as its not active anymore. The function returns thread_state::active in this case.
- Return
This function returns the previous state of the thread referenced by the id parameter. It will return one of the values as defined by the thread_state enumeration. If the thread is not known to the thread-manager the return value will be thread_state::unknown.
- Note
As long as ec is not pre-initialized to hpx::throws this function doesn’t throw but returns the result code using the parameter ec. Otherwise it throws an instance of hpx::exception.
- Parameters
id
: [in] The thread id of the thread the state should be modified for.state
: [in] The new state to be set for the thread referenced by the id parameter.stateex
: [in] The new extended state to be set for the thread referenced by the id parameter.priority
:ec
: [in,out] this represents the error status on exit, if this is pre-initialized to hpx::throws the function will throw on error instead.
-
thread_id_ref_type
set_thread_state
(thread_id_type const &id, hpx::chrono::steady_time_point const &abs_time, std::atomic<bool> *started, thread_schedule_state state = thread_schedule_state::pending, thread_restart_state stateex = thread_restart_state::timeout, thread_priority priority = thread_priority::normal, bool retry_on_active = true, error_code &ec = throws)¶ Set the thread state of the thread referenced by the thread_id id.
Set a timer to set the state of the given thread to the given new value after it expired (at the given time)
- Return
- Note
As long as ec is not pre-initialized to hpx::throws this function doesn’t throw but returns the result code using the parameter ec. Otherwise it throws an instance of hpx::exception.
- Parameters
id
: [in] The thread id of the thread the state should be modified for.abs_time
: [in] Absolute point in time for the new thread to be runstarted
: [in,out] A helper variable allowing to track the state of the timer helper threadstate
: [in] The new state to be set for the thread referenced by the id parameter.stateex
: [in] The new extended state to be set for the thread referenced by the id parameter.priority
:ec
: [in,out] this represents the error status on exit, if this is pre-initialized to hpx::throws the function will throw on error instead.
-
thread_id_ref_type
set_thread_state
(thread_id_type const &id, hpx::chrono::steady_time_point const &abs_time, thread_schedule_state state = thread_schedule_state::pending, thread_restart_state stateex = thread_restart_state::timeout, thread_priority priority = thread_priority::normal, bool retry_on_active = true, error_code& = throws)¶
-
thread_id_ref_type
set_thread_state
(thread_id_type const &id, hpx::chrono::steady_duration const &rel_time, thread_schedule_state state = thread_schedule_state::pending, thread_restart_state stateex = thread_restart_state::timeout, thread_priority priority = thread_priority::normal, bool retry_on_active = true, error_code &ec = throws)¶ Set the thread state of the thread referenced by the thread_id id.
Set a timer to set the state of the given thread to the given new value after it expired (after the given duration)
- Return
- Note
As long as ec is not pre-initialized to hpx::throws this function doesn’t throw but returns the result code using the parameter ec. Otherwise it throws an instance of hpx::exception.
- Parameters
id
: [in] The thread id of the thread the state should be modified for.rel_time
: [in] Time duration after which the new thread should be runstate
: [in] The new state to be set for the thread referenced by the id parameter.stateex
: [in] The new extended state to be set for the thread referenced by the id parameter.priority
:ec
: [in,out] this represents the error status on exit, if this is pre-initialized to hpx::throws the function will throw on error instead.
-
thread_state
get_thread_state
(thread_id_type const &id, error_code &ec = throws)¶ The function get_thread_backtrace is part of the thread related API allows to query the currently stored thread back trace (which is captured during thread suspension).
- Return
This function returns the currently captured stack back trace of the thread referenced by the id parameter. If the thread is not known to the thread-manager the return value will be the zero.
- Note
As long as ec is not pre-initialized to hpx::throws this function doesn’t throw but returns the result code using the parameter ec. Otherwise it throws an instance of hpx::exception. The function get_thread_state is part of the thread related API. It queries the state of one of the threads known to the thread-manager.
- Return
This function returns the thread state of the thread referenced by the id parameter. If the thread is not known to the thread-manager the return value will be terminated.
- Note
As long as ec is not pre-initialized to hpx::throws this function doesn’t throw but returns the result code using the parameter ec. Otherwise it throws an instance of hpx::exception.
- Parameters
id
: [in] The thread id of the thread being queried.ec
: [in,out] this represents the error status on exit, if this is pre-initialized to hpx::throws the function will throw on error instead.
- Parameters
id
: [in] The thread id of the thread the state should be modified for.ec
: [in,out] this represents the error status on exit, if this is pre-initialized to hpx::throws the function will throw on error instead.
-
std::size_t
get_thread_phase
(thread_id_type const &id, error_code &ec = throws)¶ The function get_thread_phase is part of the thread related API. It queries the phase of one of the threads known to the thread-manager.
- Return
This function returns the thread phase of the thread referenced by the id parameter. If the thread is not known to the thread-manager the return value will be ~0.
- Note
As long as ec is not pre-initialized to hpx::throws this function doesn’t throw but returns the result code using the parameter ec. Otherwise it throws an instance of hpx::exception.
- Parameters
id
: [in] The thread id of the thread the phase should be modified for.ec
: [in,out] this represents the error status on exit, if this is pre-initialized to hpx::throws the function will throw on error instead.
-
bool
get_thread_interruption_enabled
(thread_id_type const &id, error_code &ec = throws)¶ Returns whether the given thread can be interrupted at this point.
- Return
This function returns true if the given thread can be interrupted at this point in time. It will return false otherwise.
- Note
As long as ec is not pre-initialized to hpx::throws this function doesn’t throw but returns the result code using the parameter ec. Otherwise it throws an instance of hpx::exception.
- Parameters
id
: [in] The thread id of the thread which should be queried.ec
: [in,out] this represents the error status on exit, if this is pre-initialized to hpx::throws the function will throw on error instead.
-
bool
set_thread_interruption_enabled
(thread_id_type const &id, bool enable, error_code &ec = throws)¶ Set whether the given thread can be interrupted at this point.
- Return
This function returns the previous value of whether the given thread could have been interrupted.
- Note
As long as ec is not pre-initialized to hpx::throws this function doesn’t throw but returns the result code using the parameter ec. Otherwise it throws an instance of hpx::exception.
- Parameters
id
: [in] The thread id of the thread which should receive the new value.enable
: [in] This value will determine the new interruption enabled status for the given thread.ec
: [in,out] this represents the error status on exit, if this is pre-initialized to hpx::throws the function will throw on error instead.
-
bool
get_thread_interruption_requested
(thread_id_type const &id, error_code &ec = throws)¶ Returns whether the given thread has been flagged for interruption.
- Return
This function returns true if the given thread was flagged for interruption. It will return false otherwise.
- Note
As long as ec is not pre-initialized to hpx::throws this function doesn’t throw but returns the result code using the parameter ec. Otherwise it throws an instance of hpx::exception.
- Parameters
id
: [in] The thread id of the thread which should be queried.ec
: [in,out] this represents the error status on exit, if this is pre-initialized to hpx::throws the function will throw on error instead.
-
void
interrupt_thread
(thread_id_type const &id, bool flag, error_code &ec = throws)¶ Flag the given thread for interruption.
- Note
As long as ec is not pre-initialized to hpx::throws this function doesn’t throw but returns the result code using the parameter ec. Otherwise it throws an instance of hpx::exception.
- Parameters
id
: [in] The thread id of the thread which should be interrupted.flag
: [in] The flag encodes whether the thread should be interrupted (if it is true), or ‘uninterrupted’ (if it is false).ec
: [in,out] this represents the error status on exit, if this is pre-initialized to hpx::throws the function will throw on error instead.
-
void
interrupt_thread
(thread_id_type const &id, error_code &ec = throws)¶
-
void
interruption_point
(thread_id_type const &id, error_code &ec = throws)¶ Interrupt the current thread at this point if it was canceled. This will throw a thread_interrupted exception, which will cancel the thread.
- Note
As long as ec is not pre-initialized to hpx::throws this function doesn’t throw but returns the result code using the parameter ec. Otherwise it throws an instance of hpx::exception.
- Parameters
id
: [in] The thread id of the thread which should be interrupted.ec
: [in,out] this represents the error status on exit, if this is pre-initialized to hpx::throws the function will throw on error instead.
-
threads::thread_priority
get_thread_priority
(thread_id_type const &id, error_code &ec = throws)¶ Return priority of the given thread
- Note
As long as ec is not pre-initialized to hpx::throws this function doesn’t throw but returns the result code using the parameter ec. Otherwise it throws an instance of hpx::exception.
- Parameters
id
: [in] The thread id of the thread whose priority is queried.ec
: [in,out] this represents the error status on exit, if this is pre-initialized to hpx::throws the function will throw on error instead.
-
std::ptrdiff_t
get_stack_size
(thread_id_type const &id, error_code &ec = throws)¶ Return stack size of the given thread
- Note
As long as ec is not pre-initialized to hpx::throws this function doesn’t throw but returns the result code using the parameter ec. Otherwise it throws an instance of hpx::exception.
- Parameters
id
: [in] The thread id of the thread whose priority is queried.ec
: [in,out] this represents the error status on exit, if this is pre-initialized to hpx::throws the function will throw on error instead.
-
threads::thread_pool_base *
get_pool
(thread_id_type const &id, error_code &ec = throws)¶ Returns a pointer to the pool that was used to run the current thread
- Exceptions
If
:&ec != &throws
, never throws, but will set ec to an appropriate value when an error occurs. Otherwise, this function will throw an hpx::exception with an error code of hpx::yield_aborted if it is signaled with wait_aborted. If called outside of a HPX-thread, this function will throw an hpx::exception with an error code of hpx::null_thread_id. If this function is called while the thread-manager is not running, it will throw an hpx::exception with an error code of hpx::invalid_status.
-
thread_state
-
namespace