Documentation Home >> Headers >> <mutex> Header >> std::call_once function template

std::call_once is used with an instance of std::once_flag to ensure that a particular function is called exactly once, even if multiple threads invoke the call concurrently.

template<typename Callable,typename... Args>
void call_once(
    std::once_flag& flag,Callable func,Args args...);

Preconditions:

The expression INVOKE(func,args) is valid for the supplied values of func and args. Callable and every member of Args is MoveConstructible.

Effects:

Invocations of std::call_once on the same std::once_flag object are serialized. If there has been no prior effective std::call_once invocation on the same std::once_flag object, the argument func (or a copy thereof) is called as-if by INVOKE(func,args), and the invocation of std::call_once is effective if and only if the invocation of func returns without throwing an exception. If an exception is thrown, the exception is propagated to the caller. If there has been a prior effective std::call_once on the same std::once_flag object, the invocation of std::call_once returns without invoking func.

Synchronization:

The completion of an effective std::call_once invocation on a std::once_flag object, happens-before all subsequent std::call_once invocations on the same std::once_flag object.

Throws:

std::system_error when the effects cannot be achieved, or any exception propagated from the invocation of func.

Note:

On compilers that don't support variadic templates, an overloaded set of function templates is provided that supports passing of up to 5 arguments.

Header

#include <mutex>

See Also