Boost C++ Libraries Home Libraries People FAQ More

PrevUpHomeNext

One-time Initialization

Typedef once_flag
Non-member function call_once
#include <boost/thread/once.hpp>

namespace boost
{
  struct once_flag;
  template<typename Function, class ...ArgTypes>
  inline void call_once(once_flag& flag, Function&& f, ArgTypes&&... args);

#if defined BOOST_THREAD_PROVIDES_DEPRECATED_FEATURES_SINCE_V3_0_0
  void call_once(void (*func)(),once_flag& flag);
#endif

}
[Warning] Warning

the variadic prototype is provided only on C++11 compilers supporting variadic templates, otherwise the interface is limited up to 3 parameters.

[Warning] Warning

the move semantics is ensured only on C++11 compilers supporting SFINAE expression, decltype N3276 and auto. Waiting for a boost::bind that is move aware.

boost::call_once provides a mechanism for ensuring that an initialization routine is run exactly once without data races or deadlocks.

#ifdef BOOST_THREAD_PROVIDES_ONCE_CXX11
struct once_flag
{
  constexprr once_flag() noexcept;
  once_flag(const once_flag&) = delete;
  once_flag& operator=(const once_flag&) = delete;
};
#else
typedef platform-specific-type once_flag;
#define BOOST_ONCE_INIT platform-specific-initializer
#endif

Objects of type boost::once_flag shall be initialized with BOOST_ONCE_INIT if BOOST_THREAD_PROVIDES_ONCE_CXX11 is not defined

boost::once_flag f=BOOST_ONCE_INIT;
template<typename Function, class ...ArgTypes>
inline void call_once(once_flag& flag, Function&& f, ArgTypes&&... args);

Requires:

Function and each or the ArgTypes are MoveConstructible and invoke(decay_copy(boost::forward<Function>(f)), decay_copy(boost::forward<ArgTypes>(args))...) shall be well formed.

Effects:

Calls to call_once on the same once_flag object are serialized. If there has been no prior effective call_once on the same once_flag object, the argument func is called as-if by invoking invoke(decay_copy(boost::forward<Function>(f)), decay_copy(boost::forward<ArgTypes>(args))...), and the invocation of call_once is effective if and only if invoke(decay_copy(boost::forward<Function>(f)), decay_copy(boost::forward<ArgTypes>(args))...) returns without exception. If an exception is thrown, the exception is propagated to the caller. If there has been a prior effective call_once on the same once_flag object, the call_once returns without invoking func.

Synchronization:

The completion of an effective call_once invocation on a once_flag object, synchronizes with all subsequent call_once invocations on the same once_flag object.

Throws:

thread_resource_error when the effects cannot be achieved or any exception propagated from func.

Note:

The function passed to call_once must not also call call_once passing the same once_flag object. This may cause deadlock, or invoking the passed function a second time. The alternative is to allow the second call to return immediately, but that assumes the code knows it has been called recursively, and can proceed even though the call to call_once didn't actually call the function, in which case it could also avoid calling call_once recursively.

Note:

On some compilers this function has some restrictions, e.g. if variadic templates are not supported the number of arguments is limited to 3; .

void call_once(void (*func)(),once_flag& flag);

This second overload is provided for backwards compatibility and is deprecated. The effects of call_once(func,flag) shall be the same as those of call_once(flag,func).


PrevUpHomeNext