| [/ |
| (C) Copyright 2007-8 Anthony Williams. |
| Distributed under the Boost Software License, Version 1.0. |
| (See accompanying file LICENSE_1_0.txt or copy at |
| http://www.boost.org/LICENSE_1_0.txt). |
| ] |
| |
| [section:once One-time Initialization] |
| |
| `boost::call_once` provides a mechanism for ensuring that an initialization routine is run exactly once without data races or deadlocks. |
| |
| [section:once_flag Typedef `once_flag`] |
| |
| #include <boost/thread/once.hpp> |
| |
| typedef platform-specific-type once_flag; |
| #define BOOST_ONCE_INIT platform-specific-initializer |
| |
| Objects of type `boost::once_flag` shall be initialized with `BOOST_ONCE_INIT`: |
| |
| boost::once_flag f=BOOST_ONCE_INIT; |
| |
| [endsect] |
| |
| [section:call_once Non-member function `call_once`] |
| |
| #include <boost/thread/once.hpp> |
| |
| template<typename Callable> |
| void call_once(once_flag& flag,Callable func); |
| |
| [variablelist |
| |
| [[Requires:] [`Callable` is `CopyConstructible`. Copying `func` shall have no side effects, and the effect of calling the copy shall |
| be equivalent to calling the original. ]] |
| |
| [[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` (or a copy thereof) is called as-if by invoking `func()`, and the invocation of |
| `call_once` is effective if and only if `func()` 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.]] |
| |
| ] |
| |
| void call_once(void (*func)(),once_flag& flag); |
| |
| This second overload is provided for backwards compatibility. The effects of `call_once(func,flag)` shall be the same as those of |
| `call_once(flag,func)`. |
| |
| [endsect] |
| [endsect] |