mirror of
https://github.com/boostorg/thread.git
synced 2026-01-26 07:02:12 +00:00
89 lines
3.2 KiB
XML
89 lines
3.2 KiB
XML
<?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$">
|
|
<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(once, &init);
|
|
}</programlisting>
|
|
</para></description>
|
|
|
|
<parameter name="flag">
|
|
<paramtype>once_flag&</paramtype>
|
|
</parameter>
|
|
|
|
<parameter name="func">
|
|
<paramtype>Function func</paramtype>
|
|
</parameter>
|
|
|
|
<effects>As if (in an atomic fashion):
|
|
<code>if (flag == BOOST_ONCE_INIT) func();</code>. If <code>func()</code> throws an exception, it shall be as if this
|
|
thread never invoked <code>call_once</code></effects>
|
|
|
|
<postconditions><code>flag != BOOST_ONCE_INIT</code> unless <code>func()</code> throws an exception.
|
|
</postconditions>
|
|
</function>
|
|
</namespace>
|
|
</header>
|