hpx::once_flag, hpx::call_once#

Defined in header hpx/mutex.hpp.

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

Defines

HPX_ONCE_INIT#
namespace hpx

Functions

template<typename F, typename ...Args>
void call_once(once_flag &flag, F &&f, Args&&... args)#

Executes the Callable object f exactly once, even if called concurrently, from several threads.

In detail:

  • If, by the time call_once is called, flag indicates that f was already called, call_once returns right away (such a call to call_once is known as passive).

  • Otherwise, call_once invokes std::forward<Callable>(f) with the arguments std::forward<Args>(args)… (as if by hpx::invoke). Unlike the hpx::thread constructor or hpx::async, the arguments are not moved or copied because they don’t need to be transferred to another thread of execution. (such a call to call_once is known as active).

    • If that invocation throws an exception, it is propagated to the caller of call_once, and the flag is not flipped so that another call will be attempted (such a call to call_once is known as exceptional).

    • If that invocation returns normally (such a call to call_once is known as returning), the flag is flipped, and all other calls to call_once with the same flag are guaranteed to be passive. All active calls on the same flag form a single total order consisting of zero or more exceptional calls, followed by one returning call. The end of each active call synchronizes-with the next active call in that order. The return from the returning call synchronizes-with the returns from all passive calls on the same flag: this means that all concurrent calls to call_once are guaranteed to observe any side-effects made by the active call, with no additional synchronization.

Note

If concurrent calls to call_once pass different functions f, it is unspecified which f will be called. The selected function runs in the same thread as the call_once invocation it was passed to. Initialization of function-local statics is guaranteed to occur only once even when called from multiple threads, and may be more efficient than the equivalent code using hpx::call_once. The POSIX equivalent of this function is pthread_once.

Parameters

  • flag – an object, for which exactly one function gets executed

  • f – Callable object to invoke

  • args – arguments to pass to the function

Throws

std::system_error – if any condition prevents calls to call_once from executing as specified or any exception thrown by f

struct once_flag#
#include <once.hpp>

The class hpx::once_flag is a helper structure for hpx::call_once. An object of type hpx::once_flag that is passed to multiple calls to hpx::call_once allows those calls to coordinate with each other such that only one of the calls will actually run to completion. hpx::once_flag is neither copyable nor movable.

Public Functions

HPX_NON_COPYABLE(once_flag)#
inline once_flag() noexcept#

Constructs an once_flag object. The internal state is set to indicate that no function has been called yet.

Private Members

std::atomic<long> status_#
lcos::local::event event_#

Friends

template<typename F, typename ...Args>
friend void call_once(once_flag &flag, F &&f, Args&&... args)#

Executes the Callable object f exactly once, even if called concurrently, from several threads.

In detail:

  • If, by the time call_once is called, flag indicates that f was already called, call_once returns right away (such a call to call_once is known as passive).

  • Otherwise, call_once invokes std::forward<Callable>(f) with the arguments std::forward<Args>(args)… (as if by hpx::invoke). Unlike the hpx::thread constructor or hpx::async, the arguments are not moved or copied because they don’t need to be transferred to another thread of execution. (such a call to call_once is known as active).

    • If that invocation throws an exception, it is propagated to the caller of call_once, and the flag is not flipped so that another call will be attempted (such a call to call_once is known as exceptional).

    • If that invocation returns normally (such a call to call_once is known as returning), the flag is flipped, and all other calls to call_once with the same flag are guaranteed to be passive. All active calls on the same flag form a single total order consisting of zero or more exceptional calls, followed by one returning call. The end of each active call synchronizes-with the next active call in that order. The return from the returning call synchronizes-with the returns from all passive calls on the same flag: this means that all concurrent calls to call_once are guaranteed to observe any side-effects made by the active call, with no additional synchronization.

Note

If concurrent calls to call_once pass different functions f, it is unspecified which f will be called. The selected function runs in the same thread as the call_once invocation it was passed to. Initialization of function-local statics is guaranteed to occur only once even when called from multiple threads, and may be more efficient than the equivalent code using hpx::call_once. The POSIX equivalent of this function is pthread_once.

Parameters

  • flag – an object, for which exactly one function gets executed

  • f – Callable object to invoke

  • args – arguments to pass to the function

Throws

std::system_error – if any condition prevents calls to call_once from executing as specified or any exception thrown by f

namespace lcos
namespace local

Functions

template<typename F, typename... Args>  HPX_DEPRECATED_V (1, 8, "hpx::lcos::local::call_once is deprecated, use hpx::call_once " "instead") void call_once(hpx