<?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/mutex.hpp"
  last-revision="$Date: 2006/10/15 14:52:53 $">
  <namespace name="boost">
    <class name="mutex">
		<purpose>
			<para>The <classname>mutex</classname> class is a model of the 
			<link linkend="thread.concepts.Mutex">Mutex</link> concept.</para>
		</purpose>
		
		<description>
			<para>The <classname>mutex</classname> class is a model of the 
			<link linkend="thread.concepts.Mutex">Mutex</link> concept. 
			It should be used to synchronize access to shared resources using
			<link linkend="thread.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="thread.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="thread.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="thread.concepts.ScopedLock">ScopedLock</link></entry>
						</row>
					</tbody>
				</tgroup>
			</informaltable>			
			</para>

			<para>The <classname>mutex</classname> class uses an 
			<link linkend="thread.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="thread.concepts.mutex-models">mutex models</link>
			in &Boost.Thread;, <classname>mutex</classname> leaves the 
			<link linkend="thread.concepts.sheduling-policies">scheduling policy</link>
			as <link linkend="thread.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="thread.concepts.TryMutex">TryMutex</link> concept.</para>
		</purpose>
		
		<description>
			<para>The <classname>try_mutex</classname> class is a model of the 
			<link linkend="thread.concepts.TryMutex">TryMutex</link> concept. 
			It should be used to synchronize access to shared resources using
			<link linkend="thread.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="thread.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="thread.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="thread.concepts.ScopedLock">ScopedLock</link></entry>
						</row>
						<row>
							<entry>scoped_try_lock</entry>
							<entry><link linkend="thread.concepts.ScopedTryLock">ScopedTryLock</link></entry>
						</row>
					</tbody>
				</tgroup>
			</informaltable>
			</para>

			<para>The <classname>try_mutex</classname> class uses an 
			<link linkend="thread.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="thread.concepts.mutex-models">mutex models</link>
			in &Boost.Thread;, <classname>try_mutex</classname> leaves the 
			<link linkend="thread.concepts.sheduling-policies">scheduling policy</link>
			as <link linkend="thread.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="thread.concepts.TimedMutex">TimedMutex</link> concept.</para>
		</purpose>
		
		<description>
			<para>The <classname>timed_mutex</classname> class is a model of the 
			<link linkend="thread.concepts.TimedMutex">TimedMutex</link> concept. 
			It should be used to synchronize access to shared resources using
			<link linkend="thread.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="thread.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="thread.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="thread.concepts.ScopedLock">ScopedLock</link></entry>
						</row>
						<row>
							<entry>scoped_try_lock</entry>
							<entry><link linkend="thread.concepts.ScopedTryLock">ScopedTryLock</link></entry>
						</row>
						<row>
							<entry>scoped_timed_lock</entry>
							<entry><link linkend="thread.concepts.ScopedTimedLock">ScopedTimedLock</link></entry>
						</row>
					</tbody>
				</tgroup>
			</informaltable>
			</para>

			<para>The <classname>timed_mutex</classname> class uses an 
			<link linkend="thread.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="thread.concepts.mutex-models">mutex models</link>
			in  &Boost.Thread;, <classname>timed_mutex</classname> leaves the 
			<link linkend="thread.concepts.sheduling-policies">scheduling policy</link>
			as <link linkend="thread.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>
