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

]

    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]