<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE library PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN"
  "http://www.boost.org/tools/boostbook/dtd/boostbook.dtd" [
  <!ENTITY % thread.entities SYSTEM "entities.xml">
  %thread.entities;
]>
<!-- Copyright (c) 2002-2003 William E. Kempf, Michael Glassford
     Subject to the Boost Software License, Version 1.0. 
     (See accompanying file LICENSE-1.0 or  http://www.boost.org/LICENSE-1.0)
-->
<header name="boost/thread/once.hpp"
	last-revision="$Date: 2006/10/15 14:52:53 $">
	<macro name="BOOST_ONCE_INIT">
		<purpose>The <functionname>call_once</functionname> function and
		<code>once_flag</code> type (statically initialized to 
		<macroname>BOOST_ONCE_INIT</macroname>) can be used to run a
		routine exactly once. This can be used to initialize data in a
		<link linkend="thread.glossary.thread-safe">thread-safe</link>
		manner.</purpose>
		
		<description>The implementation-defined macro 
		<macroname>BOOST_ONCE_INIT</macroname> is a constant value used to 
		initialize <code>once_flag</code> instances to indicate that the 
		logically associated routine has not been run yet. See 
		<functionname>call_once</functionname> for more details.</description>
	</macro>
		
	<namespace name="boost">
		<typedef name="once_flag">
			<purpose>The <functionname>call_once</functionname> function and
			<code>once_flag</code> type (statically initialized to 
			<macroname>BOOST_ONCE_INIT</macroname>) can be used to run a
			routine exactly once. This can be used to initialize data in a
			<link linkend="thread.glossary.thread-safe">thread-safe</link>
			manner.</purpose>
			
			<description>The implementation-defined type <code>once_flag</code>
			is used as a flag to insure a routine is called only once.
			Instances of this type should be statically initialized to
			<macroname>BOOST_ONCE_INIT</macroname>. See 
			<functionname>call_once</functionname> for more details.
			</description>

			<type><emphasis>implementation-defined</emphasis></type>
		</typedef>

		<function name="call_once">
			<purpose>The <functionname>call_once</functionname> function and
			<code>once_flag</code> type (statically initialized to 
			<macroname>BOOST_ONCE_INIT</macroname>) can be used to run a
			routine exactly once. This can be used to initialize data in a
			<link linkend="thread.glossary.thread-safe">thread-safe</link>
			manner.</purpose>
			
			<description>
			<para>Example usage is as follows:</para>
			<para>
<programlisting>//Example usage:
boost::once_flag once = BOOST_ONCE_INIT;

void init()
{
    //...
}

void thread_proc()
{
    boost::call_once(&amp;init, once);
}</programlisting>
			</para></description>
			
			<parameter name="func">
				<paramtype>void (*func)()</paramtype>
			</parameter>
			
			<parameter name="flag">
				<paramtype>once_flag&amp;</paramtype>
			</parameter>
			
			<requires>The function <code>func</code> shall not throw
			exceptions.</requires>
			
			<effects>As if (in an atomic fashion): 
			<code>if (flag == BOOST_ONCE_INIT) func();</code></effects>
			
			<postconditions><code>flag != BOOST_ONCE_INIT</code>
			</postconditions>
		</function>
	</namespace>
</header>
