1[/ 2 (C) Copyright 2007-8 Anthony Williams. 3 Distributed under the Boost Software License, Version 1.0. 4 (See accompanying file LICENSE_1_0.txt or copy at 5 http://www.boost.org/LICENSE_1_0.txt). 6] 7 8[section:once One-time Initialization] 9 10 #include <boost/thread/once.hpp> 11 12 namespace boost 13 { 14 struct once_flag; 15 template<typename Function, class ...ArgTypes> 16 inline void call_once(once_flag& flag, Function&& f, ArgTypes&&... args); 17 18 #if defined BOOST_THREAD_PROVIDES_DEPRECATED_FEATURES_SINCE_V3_0_0 19 void call_once(void (*func)(),once_flag& flag); 20 #endif 21 22 } 23 24[warning the variadic prototype is provided only on C++11 compilers supporting variadic templates, otherwise the interface is limited up to 3 parameters.] 25 26[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.] 27 28 29`boost::call_once` provides a mechanism for ensuring that an initialization routine is run exactly once without data races or deadlocks. 30 31[section:once_flag Typedef `once_flag`] 32 33 #ifdef BOOST_THREAD_PROVIDES_ONCE_CXX11 34 struct once_flag 35 { 36 constexpr once_flag() noexcept; 37 once_flag(const once_flag&) = delete; 38 once_flag& operator=(const once_flag&) = delete; 39 }; 40 #else 41 typedef platform-specific-type once_flag; 42 #define BOOST_ONCE_INIT platform-specific-initializer 43 #endif 44 45Objects of type `boost::once_flag` shall be initialized with `BOOST_ONCE_INIT` if BOOST_THREAD_PROVIDES_ONCE_CXX11 is not defined 46 47 boost::once_flag f=BOOST_ONCE_INIT; 48 49[endsect] 50 51[section:call_once Non-member function `call_once`] 52 53 template<typename Function, class ...ArgTypes> 54 inline void call_once(once_flag& flag, Function&& f, ArgTypes&&... args); 55 56[variablelist 57 58[[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. ]] 59 60[[Effects:] [Calls to `call_once` on the same `once_flag` object are serialized. If there has been no prior effective `call_once` on 61the 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 62`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 63without invoking `func`. ]] 64 65[[Synchronization:] [The completion of an effective `call_once` invocation on a `once_flag` object, synchronizes with 66all subsequent `call_once` invocations on the same `once_flag` object. ]] 67 68[[Throws:] [`thread_resource_error` when the effects cannot be achieved or any exception propagated from `func`.]] 69 70[[Note:] [The function passed to `call_once` must not also call 71`call_once` passing the same `once_flag` object. This may cause 72deadlock, or invoking the passed function a second time. The 73alternative is to allow the second call to return immediately, but 74that assumes the code knows it has been called recursively, and can 75proceed even though the call to `call_once` didn't actually call the 76function, in which case it could also avoid calling `call_once` 77recursively.]] 78 79 80[[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; .]] 81 82] 83 84 void call_once(void (*func)(),once_flag& flag); 85 86This second overload is provided for backwards compatibility and is deprecated. The effects of `call_once(func,flag)` shall be the same as those of 87`call_once(flag,func)`. 88 89[endsect] 90[endsect] 91