hpx/threading_base/thread_helpers.hpp

Defined in header 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 nextid, threads::thread_description const &description = threads::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.

Throws

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::error::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::error::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::error::invalid_status.

inline threads::thread_restart_state suspend(threads::thread_schedule_state state = threads::thread_schedule_state::pending, threads::thread_description const &description = threads::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.

Throws

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::error::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::error::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::error::invalid_status.

threads::thread_restart_state suspend(hpx::chrono::steady_time_point const &abs_time, threads::thread_id_type id, threads::thread_description const &description = threads::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.

Throws

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::error::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::error::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::error::invalid_status.

inline threads::thread_restart_state suspend(hpx::chrono::steady_time_point const &abs_time, threads::thread_description const &description = threads::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.

Throws

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::error::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::error::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::error::invalid_status.

inline threads::thread_restart_state suspend(hpx::chrono::steady_duration const &rel_time, threads::thread_description const &description = threads::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.

Throws

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::error::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::error::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::error::invalid_status.

inline threads::thread_restart_state suspend(hpx::chrono::steady_duration const &rel_time, threads::thread_id_type const &id, threads::thread_description const &description = threads::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.

Throws

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::error::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::error::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::error::invalid_status.

inline threads::thread_restart_state suspend(std::uint64_t ms, threads::thread_description const &description = threads::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.

Throws

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::error::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::error::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::error::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

Throws

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::error::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::error::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::error::invalid_status.

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.

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 – [in]

• retry_on_active – [in]

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

Returns

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.

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)

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 run

• started – [in,out] A helper variable allowing to track the state of the timer helper thread

• 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 – [in]

• retry_on_active – [in]

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

Returns

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

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

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 run

• 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 – [in]

• retry_on_active – [in]

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

Returns

thread_state get_thread_state(thread_id_type const &id, error_code &ec = throws) noexcept

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

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.

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.

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

Returns

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.

Returns

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.

std::size_t get_thread_phase(thread_id_type const &id, error_code &ec = throws) noexcept

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.

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.

Returns

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.

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.

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.

Returns

This function returns true if the given thread can be interrupted at this point in time. It will return false otherwise.

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.

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.

Returns

This function returns the previous value of whether the given thread could have been interrupted.

bool get_thread_interruption_requested(thread_id_type const &id, error_code &ec = throws)

Returns whether the given thread has been flagged 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 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.

Returns

This function returns true if the given thread was flagged for interruption. It will return false otherwise.

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.

inline 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) noexcept

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

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

Throws

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::error::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::error::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::error::invalid_status.