mirror of
https://github.com/boostorg/thread.git
synced 2026-01-23 18:12:12 +00:00
306 lines
11 KiB
XML
306 lines
11 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 % threads.entities SYSTEM "entities.xml">
|
|
%threads.entities;
|
|
]>
|
|
<header name="boost/thread/mutex.hpp"
|
|
last-revision="$Date$">
|
|
<namespace name="boost">
|
|
<class name="mutex">
|
|
<purpose>
|
|
<para>The <classname>mutex</classname> class is a model of the
|
|
<link linkend="threads.concepts.Mutex">Mutex</link> concept.</para>
|
|
</purpose>
|
|
|
|
<description>
|
|
<para>The <classname>mutex</classname> class is a model of the
|
|
<link linkend="threads.concepts.Mutex">Mutex</link> concept.
|
|
It should be used to synchronize access to shared resources using
|
|
<link linkend="threads.concepts.unspecified-locking-strategy">Unspecified</link>
|
|
locking mechanics.</para>
|
|
|
|
<para>For classes that model related mutex concepts, see
|
|
<classname>try_mutex</classname> and <classname>timed_mutex</classname>.</para>
|
|
|
|
<para>For <link linkend="threads.concepts.recursive-locking-strategy">Recursive</link>
|
|
locking mechanics, see <classname>recursive_mutex</classname>,
|
|
<classname>recursive_try_mutex</classname>, and <classname>recursive_timed_mutex</classname>.
|
|
</para>
|
|
|
|
<para>The <classname>mutex</classname> class supplies the following typedef,
|
|
which <link linkend="threads.concepts.lock-models">models</link>
|
|
the specified locking strategy:
|
|
|
|
<informaltable>
|
|
<tgroup cols="2" align="left">
|
|
<thead>
|
|
<row>
|
|
<entry>Lock Name</entry>
|
|
<entry>Lock Concept</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>scoped_lock</entry>
|
|
<entry><link linkend="threads.concepts.ScopedLock">ScopedLock</link></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
</para>
|
|
|
|
<para>The <classname>mutex</classname> class uses an
|
|
<link linkend="threads.concepts.unspecified-locking-strategy">Unspecified</link>
|
|
locking strategy, so attempts to recursively lock a <classname>mutex</classname>
|
|
object or attempts to unlock one by threads that don't own a lock on it result in
|
|
<emphasis role="bold">undefined behavior</emphasis>.
|
|
This strategy allows implementations to be as efficient as possible
|
|
on any given platform. It is, however, recommended that
|
|
implementations include debugging support to detect misuse when
|
|
<code>NDEBUG</code> is not defined.</para>
|
|
|
|
<para>Like all
|
|
<link linkend="threads.concepts.mutex-models">mutex models</link>
|
|
in &Boost.Threads;, <classname>mutex</classname> leaves the
|
|
<link linkend="threads.concepts.sheduling-policies">scheduling policy</link>
|
|
as <link linkend="threads.concepts.unspecified-scheduling-policy">Unspecified</link>.
|
|
Programmers should make no assumptions about the order in which
|
|
waiting threads acquire a lock.</para>
|
|
</description>
|
|
|
|
<inherit access="private">
|
|
<type><classname>boost::noncopyable</classname></type>
|
|
<purpose>Exposition only</purpose>
|
|
</inherit>
|
|
|
|
<typedef name="scoped_lock">
|
|
<type><emphasis>implementation-defined</emphasis></type>
|
|
</typedef>
|
|
|
|
<constructor>
|
|
<effects>Constructs a <classname>mutex</classname> object.
|
|
</effects>
|
|
|
|
<postconditions><code>*this</code> is in an unlocked state.
|
|
</postconditions>
|
|
</constructor>
|
|
|
|
<destructor>
|
|
<effects>Destroys a <classname>mutex</classname> object.</effects>
|
|
|
|
<requires><code>*this</code> is in an unlocked state.</requires>
|
|
|
|
<notes><emphasis role="bold">Danger:</emphasis> Destruction of a
|
|
locked mutex is a serious programming error resulting in undefined
|
|
behavior such as a program crash.</notes>
|
|
</destructor>
|
|
</class>
|
|
|
|
<class name="try_mutex">
|
|
<purpose>
|
|
<para>The <classname>try_mutex</classname> class is a model of the
|
|
<link linkend="threads.concepts.TryMutex">TryMutex</link> concept.</para>
|
|
</purpose>
|
|
|
|
<description>
|
|
<para>The <classname>try_mutex</classname> class is a model of the
|
|
<link linkend="threads.concepts.TryMutex">TryMutex</link> concept.
|
|
It should be used to synchronize access to shared resources using
|
|
<link linkend="threads.concepts.unspecified-locking-strategy">Unspecified</link>
|
|
locking mechanics.</para>
|
|
|
|
<para>For classes that model related mutex concepts, see
|
|
<classname>mutex</classname> and <classname>timed_mutex</classname>.</para>
|
|
|
|
<para>For <link linkend="threads.concepts.recursive-locking-strategy">Recursive</link>
|
|
locking mechanics, see <classname>recursive_mutex</classname>,
|
|
<classname>recursive_try_mutex</classname>, and <classname>recursive_timed_mutex</classname>.
|
|
</para>
|
|
|
|
<para>The <classname>try_mutex</classname> class supplies the following typedefs,
|
|
which <link linkend="threads.concepts.lock-models">model</link>
|
|
the specified locking strategies:
|
|
|
|
<informaltable>
|
|
<tgroup cols="2" align="left">
|
|
<thead>
|
|
<row>
|
|
<entry>Lock Name</entry>
|
|
<entry>Lock Concept</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>scoped_lock</entry>
|
|
<entry><link linkend="threads.concepts.ScopedLock">ScopedLock</link></entry>
|
|
</row>
|
|
<row>
|
|
<entry>scoped_try_lock</entry>
|
|
<entry><link linkend="threads.concepts.ScopedTryLock">ScopedTryLock</link></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
</para>
|
|
|
|
<para>The <classname>try_mutex</classname> class uses an
|
|
<link linkend="threads.concepts.unspecified-locking-strategy">Unspecified</link>
|
|
locking strategy, so attempts to recursively lock a <classname>try_mutex</classname>
|
|
object or attempts to unlock one by threads that don't own a lock on it result in
|
|
<emphasis role="bold">undefined behavior</emphasis>.
|
|
This strategy allows implementations to be as efficient as possible
|
|
on any given platform. It is, however, recommended that
|
|
implementations include debugging support to detect misuse when
|
|
<code>NDEBUG</code> is not defined.</para>
|
|
|
|
<para>Like all
|
|
<link linkend="threads.concepts.mutex-models">mutex models</link>
|
|
in &Boost.Threads;, <classname>try_mutex</classname> leaves the
|
|
<link linkend="threads.concepts.sheduling-policies">scheduling policy</link>
|
|
as <link linkend="threads.concepts.unspecified-scheduling-policy">Unspecified</link>.
|
|
Programmers should make no assumptions about the order in which
|
|
waiting threads acquire a lock.</para>
|
|
</description>
|
|
|
|
<inherit access="private">
|
|
<type><classname>boost::noncopyable</classname></type>
|
|
<purpose>Exposition only</purpose>
|
|
</inherit>
|
|
|
|
<typedef name="scoped_lock">
|
|
<type><emphasis>implementation-defined</emphasis></type>
|
|
</typedef>
|
|
|
|
<typedef name="scoped_try_lock">
|
|
<type><emphasis>implementation-defined</emphasis></type>
|
|
</typedef>
|
|
|
|
<constructor>
|
|
<effects>Constructs a <classname>try_mutex</classname> object.
|
|
</effects>
|
|
|
|
<postconditions><code>*this</code> is in an unlocked state.
|
|
</postconditions>
|
|
</constructor>
|
|
|
|
<destructor>
|
|
<effects>Destroys a <classname>try_mutex</classname> object.
|
|
</effects>
|
|
|
|
<requires><code>*this</code> is in an unlocked state.</requires>
|
|
|
|
<notes><emphasis role="bold">Danger:</emphasis> Destruction of a
|
|
locked mutex is a serious programming error resulting in undefined
|
|
behavior such as a program crash.</notes>
|
|
</destructor>
|
|
</class>
|
|
|
|
<class name="timed_mutex">
|
|
<purpose>
|
|
<para>The <classname>timed_mutex</classname> class is a model of the
|
|
<link linkend="threads.concepts.TimedMutex">TimedMutex</link> concept.</para>
|
|
</purpose>
|
|
|
|
<description>
|
|
<para>The <classname>timed_mutex</classname> class is a model of the
|
|
<link linkend="threads.concepts.TimedMutex">TimedMutex</link> concept.
|
|
It should be used to synchronize access to shared resources using
|
|
<link linkend="threads.concepts.unspecified-locking-strategy">Unspecified</link>
|
|
locking mechanics.</para>
|
|
|
|
<para>For classes that model related mutex concepts, see
|
|
<classname>mutex</classname> and <classname>try_mutex</classname>.</para>
|
|
|
|
<para>For <link linkend="threads.concepts.recursive-locking-strategy">Recursive</link>
|
|
locking mechanics, see <classname>recursive_mutex</classname>,
|
|
<classname>recursive_try_mutex</classname>, and <classname>recursive_timed_mutex</classname>.
|
|
</para>
|
|
|
|
<para>The <classname>timed_mutex</classname> class supplies the following typedefs,
|
|
which <link linkend="threads.concepts.lock-models">model</link>
|
|
the specified locking strategies:
|
|
|
|
<informaltable>
|
|
<tgroup cols="2" align="left">
|
|
<thead>
|
|
<row>
|
|
<entry>Lock Name</entry>
|
|
<entry>Lock Concept</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>scoped_lock</entry>
|
|
<entry><link linkend="threads.concepts.ScopedLock">ScopedLock</link></entry>
|
|
</row>
|
|
<row>
|
|
<entry>scoped_try_lock</entry>
|
|
<entry><link linkend="threads.concepts.ScopedTryLock">ScopedTryLock</link></entry>
|
|
</row>
|
|
<row>
|
|
<entry>scoped_timed_lock</entry>
|
|
<entry><link linkend="threads.concepts.ScopedTimedLock">ScopedTimedLock</link></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
</para>
|
|
|
|
<para>The <classname>timed_mutex</classname> class uses an
|
|
<link linkend="threads.concepts.unspecified-locking-strategy">Unspecified</link>
|
|
locking strategy, so attempts to recursively lock a <classname>timed_mutex</classname>
|
|
object or attempts to unlock one by threads that don't own a lock on it result in
|
|
<emphasis role="bold">undefined behavior</emphasis>.
|
|
This strategy allows implementations to be as efficient as possible
|
|
on any given platform. It is, however, recommended that
|
|
implementations include debugging support to detect misuse when
|
|
<code>NDEBUG</code> is not defined.</para>
|
|
|
|
<para>Like all
|
|
<link linkend="threads.concepts.mutex-models">mutex models</link>
|
|
in &Boost.Threads;, <classname>timed_mutex</classname> leaves the
|
|
<link linkend="threads.concepts.sheduling-policies">scheduling policy</link>
|
|
as <link linkend="threads.concepts.unspecified-scheduling-policy">Unspecified</link>.
|
|
Programmers should make no assumptions about the order in which
|
|
waiting threads acquire a lock.</para>
|
|
</description>
|
|
|
|
<inherit access="private">
|
|
<type><classname>boost::noncopyable</classname></type>
|
|
<purpose>Exposition only</purpose>
|
|
</inherit>
|
|
|
|
<typedef name="scoped_lock">
|
|
<type><emphasis>implementation-defined</emphasis></type>
|
|
</typedef>
|
|
|
|
<typedef name="scoped_try_lock">
|
|
<type><emphasis>implementation-defined</emphasis></type>
|
|
</typedef>
|
|
|
|
<typedef name="scoped_timed_lock">
|
|
<type><emphasis>implementation-defined</emphasis></type>
|
|
</typedef>
|
|
|
|
<constructor>
|
|
<effects>Constructs a <classname>timed_mutex</classname> object.
|
|
</effects>
|
|
|
|
<postconditions><code>*this</code> is in an unlocked state.
|
|
</postconditions>
|
|
</constructor>
|
|
|
|
<destructor>
|
|
<effects>Destroys a <classname>timed_mutex</classname> object.</effects>
|
|
|
|
<requires><code>*this</code> is in an unlocked state.</requires>
|
|
|
|
<notes><emphasis role="bold">Danger:</emphasis> Destruction of a
|
|
locked mutex is a serious programming error resulting in undefined
|
|
behavior such as a program crash.</notes>
|
|
</destructor>
|
|
</class>
|
|
</namespace>
|
|
</header>
|