<?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/06/08 18:48:50 $">
  <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>
    <note> Unfortunately it turned out that the current implementation of Read/Write Mutex has     
            some serious problems. So it was decided not to put this implementation into
            release grade code. Also discussions on the mailing list led to the
            conclusion that the current concepts need to be rethought. In particular
            the schedulings <link linkend="thread.concepts.read-write-scheduling-policies.inter-class">
                Inter-Class Scheduling Policies</link> are deemed unnecessary.
            There seems to be common belief that a fair scheme suffices.
            The following documentation has been retained however, to give
            readers of this document the opportunity to study the original design.
    </note>
		</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>
    <note> Unfortunately it turned out that the current implementation of Read/Write Mutex has     
            some serious problems. So it was decided not to put this implementation into
            release grade code. Also discussions on the mailing list led to the
            conclusion that the current concepts need to be rethought. In particular
            the schedulings <link linkend="thread.concepts.read-write-scheduling-policies.inter-class">
                Inter-Class Scheduling Policies</link> are deemed unnecessary.
            There seems to be common belief that a fair scheme suffices.
            The following documentation has been retained however, to give
            readers of this document the opportunity to study the original design.
    </note>
		</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>
    <note> Unfortunately it turned out that the current implementation of Read/Write Mutex has     
            some serious problems. So it was decided not to put this implementation into
            release grade code. Also discussions on the mailing list led to the
            conclusion that the current concepts need to be rethought. In particular
            the schedulings <link linkend="thread.concepts.read-write-scheduling-policies.inter-class">
                Inter-Class Scheduling Policies</link> are deemed unnecessary.
            There seems to be common belief that a fair scheme suffices.
            The following documentation has been retained however, to give
            readers of this document the opportunity to study the original design.
    </note>
		</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>
