mirror of
https://github.com/boostorg/thread.git
synced 2026-01-26 07:02:12 +00:00
493 lines
21 KiB
XML
493 lines
21 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/read_write_mutex.hpp"
|
|
last-revision="$Date$">
|
|
<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>
|