boost_1_45_0/libs/thread/doc/once.qbk

[/
  (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]