<?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/read_write_mutex.hpp"
  last-revision="$Date: 2007/01/01 14:10:28 $">
  <namespace name="boost">
	<namespace name="read_write_scheduling_policy">
		<enum name="read_write_scheduling_policy">
			<enumvalue name="writer_priority" />
			<enumvalue name="reader_priority" />
			<enumvalue name="alternating_many_reads" />
			<enumvalue name="alternating_single_read" />

			<purpose>
				<para>Specifies the 
				<link linkend="thread.concepts.read-write-scheduling-policies.inter-class">inter-class sheduling policy</link>
				to use when a set of threads try to obtain different types of
				locks simultaneously.</para>
			</purpose>

			<description>
				<para>The only clock type supported by &Boost.Thread; is 
				<code>TIME_UTC</code>. The epoch for <code>TIME_UTC</code>
				is 1970-01-01 00:00:00.</para>
			</description>
		</enum>
	</namespace>
	
    <class name="read_write_mutex">
		<purpose>
			<para>The <classname>read_write_mutex</classname> class is a model of the 
			<link linkend="thread.concepts.ReadWriteMutex">ReadWriteMutex</link> concept.</para>
		</purpose>
		
		<description>
			<para>The <classname>read_write_mutex</classname> class is a model of the 
			<link linkend="thread.concepts.ReadWriteMutex">ReadWriteMutex</link> concept. 
			It should be used to synchronize access to shared resources using
			<link linkend="thread.concepts.read-write-locking-strategies.unspecified">Unspecified</link>
			locking mechanics.</para>

			<para>For classes that model related mutex concepts, see 
			<classname>try_read_write_mutex</classname> and <classname>timed_read_write_mutex</classname>.</para>
			
			<para>The <classname>read_write_mutex</classname> class supplies the following typedefs,
			which <link linkend="thread.concepts.read-write-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_read_write_lock</entry>
							<entry><link linkend="thread.concepts.ScopedReadWriteLock">ScopedReadWriteLock</link></entry>
						</row>
						<row>
							<entry>scoped_read_lock</entry>
							<entry><link linkend="thread.concepts.ScopedLock">ScopedLock</link></entry>
						</row>
						<row>
							<entry>scoped_write_lock</entry>
							<entry><link linkend="thread.concepts.ScopedLock">ScopedLock</link></entry>
						</row>
					</tbody>
				</tgroup>
			</informaltable>			
			</para>

			<para>The <classname>read_write_mutex</classname> class uses an 
			<link linkend="thread.concepts.read-write-locking-strategies.unspecified">Unspecified</link>
			locking strategy, so attempts to recursively lock a <classname>read_write_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.read-write-mutex-models">read/write mutex models</link>
			in &Boost.Thread;, <classname>read_write_mutex</classname> has two types of
			<link linkend="thread.concepts.read-write-scheduling-policies">scheduling policies</link>, an 
			<link linkend="thread.concepts.read-write-scheduling-policies.inter-class">inter-class sheduling policy</link>
			between threads trying to obtain different types of locks and an
			<link linkend="thread.concepts.read-write-scheduling-policies.intra-class">intra-class sheduling policy</link>
			between threads trying to obtain the same type of lock.
			The <classname>read_write_mutex</classname> class allows the
			programmer to choose what
			<link linkend="thread.concepts.read-write-scheduling-policies.inter-class">inter-class sheduling policy</link>
			will be used; however, like all read/write mutex models, 
			<classname>read_write_mutex</classname> leaves the 
			<link linkend="thread.concepts.read-write-scheduling-policies.intra-class">intra-class sheduling policy</link> as 
			<link linkend="thread.concepts.read-write-locking-strategies.unspecified">Unspecified</link>.			
			</para>
			
			<note>Self-deadlock is virtually guaranteed if a thread tries to
			lock the same <classname>read_write_mutex</classname> multiple times
			unless all locks are read-locks (but see below)</note>
		</description>
		
		<inherit access="private">
			<type><classname>boost::noncopyable</classname></type>
			<purpose>Exposition only</purpose>
		</inherit>
		
		<inherit access="private">
			<type><classname>boost::noncopyable</classname></type>
			<purpose>Exposition only</purpose>
		</inherit>
		
		<typedef name="scoped_read_write_lock">
			<type><emphasis>implementation-defined</emphasis></type>
		</typedef>
		
		<typedef name="scoped_read_lock">
			<type><emphasis>implementation-defined</emphasis></type>
		</typedef>
		
		<typedef name="scoped_write_lock">
			<type><emphasis>implementation-defined</emphasis></type>
		</typedef>
		
		<constructor>
			<parameter name="count">
				<paramtype>boost::read_write_scheduling_policy</paramtype>
			</parameter>

			<effects>Constructs a <classname>read_write_mutex</classname> object.
			</effects>
			
			<postconditions><code>*this</code> is in an unlocked state.
			</postconditions>
		</constructor>

		<destructor>
			<effects>Destroys a <classname>read_write_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_read_write_mutex">
		<purpose>
			<para>The <classname>try_read_write_mutex</classname> class is a model of the 
			<link linkend="thread.concepts.TryReadWriteMutex">TryReadWriteMutex</link> concept.</para>
		</purpose>
		
		<description>
			<para>The <classname>try_read_write_mutex</classname> class is a model of the 
			<link linkend="thread.concepts.TryReadWriteMutex">TryReadWriteMutex</link> concept. 
			It should be used to synchronize access to shared resources using
			<link linkend="thread.concepts.read-write-locking-strategies.unspecified">Unspecified</link>
			locking mechanics.</para>

			<para>For classes that model related mutex concepts, see 
			<classname>read_write_mutex</classname> and <classname>timed_read_write_mutex</classname>.</para>
			
			<para>The <classname>try_read_write_mutex</classname> class supplies the following typedefs,
			which <link linkend="thread.concepts.read-write-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_read_write_lock</entry>
							<entry><link linkend="thread.concepts.ScopedReadWriteLock">ScopedReadWriteLock</link></entry>
						</row>
						<row>
							<entry>scoped_try_read_write_lock</entry>
							<entry><link linkend="thread.concepts.ScopedTryReadWriteLock">ScopedTryReadWriteLock</link></entry>
						</row>
						<row>
							<entry>scoped_read_lock</entry>
							<entry><link linkend="thread.concepts.ScopedLock">ScopedLock</link></entry>
						</row>
						<row>
							<entry>scoped_try_read_lock</entry>
							<entry><link linkend="thread.concepts.ScopedTryLock">ScopedTryLock</link></entry>
						</row>
						<row>
							<entry>scoped_write_lock</entry>
							<entry><link linkend="thread.concepts.ScopedLock">ScopedLock</link></entry>
						</row>
						<row>
							<entry>scoped_try_write_lock</entry>
							<entry><link linkend="thread.concepts.ScopedTryLock">ScopedTryLock</link></entry>
						</row>
					</tbody>
				</tgroup>
			</informaltable>			
			</para>

			<para>The <classname>try_read_write_mutex</classname> class uses an 
			<link linkend="thread.concepts.read-write-locking-strategies.unspecified">Unspecified</link>
			locking strategy, so attempts to recursively lock a <classname>try_read_write_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.read-write-mutex-models">read/write mutex models</link>
			in &Boost.Thread;, <classname>try_read_write_mutex</classname> has two types of
			<link linkend="thread.concepts.read-write-scheduling-policies">scheduling policies</link>, an 
			<link linkend="thread.concepts.read-write-scheduling-policies.inter-class">inter-class sheduling policy</link>
			between threads trying to obtain different types of locks and an
			<link linkend="thread.concepts.read-write-scheduling-policies.intra-class">intra-class sheduling policy</link>
			between threads trying to obtain the same type of lock.
			The <classname>try_read_write_mutex</classname> class allows the
			programmer to choose what
			<link linkend="thread.concepts.read-write-scheduling-policies.inter-class">inter-class sheduling policy</link>
			will be used; however, like all read/write mutex models, 
			<classname>try_read_write_mutex</classname> leaves the 
			<link linkend="thread.concepts.read-write-scheduling-policies.intra-class">intra-class sheduling policy</link> as 
			<link linkend="thread.concepts.unspecified-scheduling-policy">Unspecified</link>.			
			</para>
			
			<note>Self-deadlock is virtually guaranteed if a thread tries to
			lock the same <classname>try_read_write_mutex</classname> multiple times
			unless all locks are read-locks (but see below)</note>
		</description>
		
		<inherit access="private">
			<type><classname>boost::noncopyable</classname></type>
			<purpose>Exposition only</purpose>
		</inherit>
		
		<typedef name="scoped_read_write_lock">
			<type><emphasis>implementation-defined</emphasis></type>
		</typedef>
		
		<typedef name="scoped_try_read_write_lock">
			<type><emphasis>implementation-defined</emphasis></type>
		</typedef>
		
		<typedef name="scoped_read_lock">
			<type><emphasis>implementation-defined</emphasis></type>
		</typedef>
		
		<typedef name="scoped_try_read_lock">
			<type><emphasis>implementation-defined</emphasis></type>
		</typedef>
		
		<typedef name="scoped_write_lock">
			<type><emphasis>implementation-defined</emphasis></type>
		</typedef>
		
		<typedef name="scoped_try_write_lock">
			<type><emphasis>implementation-defined</emphasis></type>
		</typedef>
		
		<constructor>
			<parameter name="count">
				<paramtype>boost::read_write_scheduling_policy</paramtype>
			</parameter>

			<effects>Constructs a <classname>try_read_write_mutex</classname> object.
			</effects>
			
			<postconditions><code>*this</code> is in an unlocked state.
			</postconditions>
		</constructor>

		<destructor>
			<effects>Destroys a <classname>try_read_write_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_read_write_mutex">
		<purpose>
			<para>The <classname>timed_read_write_mutex</classname> class is a model of the 
			<link linkend="thread.concepts.TimedReadWriteMutex">TimedReadWriteMutex</link> concept.</para>
		</purpose>
		
		<description>
			<para>The <classname>timed_read_write_mutex</classname> class is a model of the 
			<link linkend="thread.concepts.TimedReadWriteMutex">TimedReadWriteMutex</link> concept. 
			It should be used to synchronize access to shared resources using
			<link linkend="thread.concepts.read-write-locking-strategies.unspecified">Unspecified</link>
			locking mechanics.</para>

			<para>For classes that model related mutex concepts, see 
			<classname>read_write_mutex</classname> and <classname>try_read_write_mutex</classname>.</para>
			
			<para>The <classname>timed_read_write_mutex</classname> class supplies the following typedefs,
			which <link linkend="thread.concepts.read-write-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_read_write_lock</entry>
							<entry><link linkend="thread.concepts.ScopedReadWriteLock">ScopedReadWriteLock</link></entry>
						</row>
						<row>
							<entry>scoped_try_read_write_lock</entry>
							<entry><link linkend="thread.concepts.ScopedTryReadWriteLock">ScopedTryReadWriteLock</link></entry>
						</row>
						<row>
							<entry>scoped_timed_read_write_lock</entry>
							<entry><link linkend="thread.concepts.ScopedTimedReadWriteLock">ScopedTimedReadWriteLock</link></entry>
						</row>
						<row>
							<entry>scoped_read_lock</entry>
							<entry><link linkend="thread.concepts.ScopedLock">ScopedLock</link></entry>
						</row>
						<row>
							<entry>scoped_try_read_lock</entry>
							<entry><link linkend="thread.concepts.ScopedTryLock">ScopedTryLock</link></entry>
						</row>
						<row>
							<entry>scoped_timed_read_lock</entry>
							<entry><link linkend="thread.concepts.ScopedTimedLock">ScopedTimedLock</link></entry>
						</row>
						<row>
							<entry>scoped_write_lock</entry>
							<entry><link linkend="thread.concepts.ScopedLock">ScopedLock</link></entry>
						</row>
						<row>
							<entry>scoped_try_write_lock</entry>
							<entry><link linkend="thread.concepts.ScopedTryLock">ScopedTryLock</link></entry>
						</row>
						<row>
							<entry>scoped_timed_write_lock</entry>
							<entry><link linkend="thread.concepts.ScopedTimedLock">ScopedTimedLock</link></entry>
						</row>
					</tbody>
				</tgroup>
			</informaltable>			
			</para>

			<para>The <classname>timed_read_write_mutex</classname> class uses an 
			<link linkend="thread.concepts.read-write-locking-strategies.unspecified">Unspecified</link>
			locking strategy, so attempts to recursively lock a <classname>timed_read_write_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.read-write-mutex-models">read/write mutex models</link>
			in &Boost.Thread;, <classname>timed_read_write_mutex</classname> has two types of
			<link linkend="thread.concepts.read-write-scheduling-policies">scheduling policies</link>, an 
			<link linkend="thread.concepts.read-write-scheduling-policies.inter-class">inter-class sheduling policy</link>
			between threads trying to obtain different types of locks and an
			<link linkend="thread.concepts.read-write-scheduling-policies.intra-class">intra-class sheduling policy</link>
			between threads trying to obtain the same type of lock.
			The <classname>timed_read_write_mutex</classname> class allows the
			programmer to choose what
			<link linkend="thread.concepts.read-write-scheduling-policies.inter-class">inter-class sheduling policy</link>
			will be used; however, like all read/write mutex models, 
			<classname>timed_read_write_mutex</classname> leaves the 
			<link linkend="thread.concepts.read-write-scheduling-policies.intra-class">intra-class sheduling policy</link> as 
			<link linkend="thread.concepts.unspecified-scheduling-policy">Unspecified</link>.			
			</para>
			
			<note>Self-deadlock is virtually guaranteed if a thread tries to
			lock the same <classname>timed_read_write_mutex</classname> multiple times
			unless all locks are read-locks (but see below)</note>
		</description>
		
		<typedef name="scoped_read_write_lock">
			<type><emphasis>implementation-defined</emphasis></type>
		</typedef>
		
		<typedef name="scoped_try_read_write_lock">
			<type><emphasis>implementation-defined</emphasis></type>
		</typedef>
		
		<typedef name="scoped_timed_read_write_lock">
			<type><emphasis>implementation-defined</emphasis></type>
		</typedef>
		
		<typedef name="scoped_read_lock">
			<type><emphasis>implementation-defined</emphasis></type>
		</typedef>
		
		<typedef name="scoped_try_read_lock">
			<type><emphasis>implementation-defined</emphasis></type>
		</typedef>
		
		<typedef name="scoped_timed_read_lock">
			<type><emphasis>implementation-defined</emphasis></type>
		</typedef>
		
		<typedef name="scoped_write_lock">
			<type><emphasis>implementation-defined</emphasis></type>
		</typedef>
		
		<typedef name="scoped_try_write_lock">
			<type><emphasis>implementation-defined</emphasis></type>
		</typedef>
		
		<typedef name="scoped_timed_write_lock">
			<type><emphasis>implementation-defined</emphasis></type>
		</typedef>
		
		<constructor>
			<parameter name="count">
				<paramtype>boost::read_write_scheduling_policy</paramtype>
			</parameter>

			<effects>Constructs a <classname>timed_read_write_mutex</classname> object.
			</effects>
			
			<postconditions><code>*this</code> is in an unlocked state.
			</postconditions>
		</constructor>

		<destructor>
			<effects>Destroys a <classname>timed_read_write_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>
