Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: downloads/boost_1_33_1/libs/thread/doc/mutex-ref.xml @ 12

Last change on this file since 12 was 12, checked in by landauf, 17 years ago

added boost
File size: 11.2 KB
Line 
1<?xml version="1.0" encoding="utf-8"?>
2<!DOCTYPE library PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN"
3  "http://www.boost.org/tools/boostbook/dtd/boostbook.dtd" [
4  <!ENTITY % threads.entities SYSTEM "entities.xml">
5  %threads.entities;
6]>
7<header name="boost/thread/mutex.hpp"
8  last-revision="$Date: 2004/07/17 04:33:59 $">
9  <namespace name="boost">
10    <class name="mutex">
11                <purpose>
12                        <para>The <classname>mutex</classname> class is a model of the
13                        <link linkend="threads.concepts.Mutex">Mutex</link> concept.</para>
14                </purpose>
15               
16                <description>
17                        <para>The <classname>mutex</classname> class is a model of the
18                        <link linkend="threads.concepts.Mutex">Mutex</link> concept.
19                        It should be used to synchronize access to shared resources using
20                        <link linkend="threads.concepts.unspecified-locking-strategy">Unspecified</link>
21                        locking mechanics.</para>
22
23                        <para>For classes that model related mutex concepts, see
24                        <classname>try_mutex</classname> and <classname>timed_mutex</classname>.</para>
25
26                        <para>For <link linkend="threads.concepts.recursive-locking-strategy">Recursive</link>
27                        locking mechanics, see <classname>recursive_mutex</classname>,
28                        <classname>recursive_try_mutex</classname>, and <classname>recursive_timed_mutex</classname>.
29                        </para>
30                       
31                        <para>The <classname>mutex</classname> class supplies the following typedef,
32                        which <link linkend="threads.concepts.lock-models">models</link>
33                        the specified locking strategy:
34
35                        <informaltable>
36                                <tgroup cols="2" align="left">
37                                        <thead>
38                                                <row>
39                                                        <entry>Lock Name</entry>
40                                                        <entry>Lock Concept</entry>
41                                                </row>
42                                        </thead>
43                                        <tbody>
44                                                <row>
45                                                        <entry>scoped_lock</entry>
46                                                        <entry><link linkend="threads.concepts.ScopedLock">ScopedLock</link></entry>
47                                                </row>
48                                        </tbody>
49                                </tgroup>
50                        </informaltable>                       
51                        </para>
52
53                        <para>The <classname>mutex</classname> class uses an
54                        <link linkend="threads.concepts.unspecified-locking-strategy">Unspecified</link>
55                        locking strategy, so attempts to recursively lock a <classname>mutex</classname>
56                        object or attempts to unlock one by threads that don't own a lock on it result in
57                        <emphasis role="bold">undefined behavior</emphasis>.
58                        This strategy allows implementations to be as efficient as possible
59                        on any given platform. It is, however, recommended that
60                        implementations include debugging support to detect misuse when
61                        <code>NDEBUG</code> is not defined.</para>
62                       
63                        <para>Like all
64                        <link linkend="threads.concepts.mutex-models">mutex models</link>
65                        in &Boost.Threads;, <classname>mutex</classname> leaves the
66                        <link linkend="threads.concepts.sheduling-policies">scheduling policy</link>
67                        as <link linkend="threads.concepts.unspecified-scheduling-policy">Unspecified</link>.
68                        Programmers should make no assumptions about the order in which
69                        waiting threads acquire a lock.</para>
70                </description>
71               
72                <inherit access="private">
73                        <type><classname>boost::noncopyable</classname></type>
74                        <purpose>Exposition only</purpose>
75                </inherit>
76               
77                <typedef name="scoped_lock">
78                        <type><emphasis>implementation-defined</emphasis></type>
79                </typedef>
80               
81                <constructor>
82                        <effects>Constructs a <classname>mutex</classname> object.
83                        </effects>
84                       
85                        <postconditions><code>*this</code> is in an unlocked state.
86                        </postconditions>
87                </constructor>
88
89                <destructor>
90                        <effects>Destroys a <classname>mutex</classname> object.</effects>
91                       
92                        <requires><code>*this</code> is in an unlocked state.</requires>
93                       
94                        <notes><emphasis role="bold">Danger:</emphasis> Destruction of a
95                        locked mutex is a serious programming error resulting in undefined
96                        behavior such as a program crash.</notes>
97                </destructor>
98        </class>
99       
100        <class name="try_mutex">
101                <purpose>
102                        <para>The <classname>try_mutex</classname> class is a model of the
103                        <link linkend="threads.concepts.TryMutex">TryMutex</link> concept.</para>
104                </purpose>
105               
106                <description>
107                        <para>The <classname>try_mutex</classname> class is a model of the
108                        <link linkend="threads.concepts.TryMutex">TryMutex</link> concept.
109                        It should be used to synchronize access to shared resources using
110                        <link linkend="threads.concepts.unspecified-locking-strategy">Unspecified</link>
111                        locking mechanics.</para>
112
113                        <para>For classes that model related mutex concepts, see
114                        <classname>mutex</classname> and <classname>timed_mutex</classname>.</para>
115
116                        <para>For <link linkend="threads.concepts.recursive-locking-strategy">Recursive</link>
117                        locking mechanics, see <classname>recursive_mutex</classname>,
118                        <classname>recursive_try_mutex</classname>, and <classname>recursive_timed_mutex</classname>.
119                        </para>
120                       
121                        <para>The <classname>try_mutex</classname> class supplies the following typedefs,
122                        which <link linkend="threads.concepts.lock-models">model</link>
123                        the specified locking strategies:
124
125                        <informaltable>
126                                <tgroup cols="2" align="left">
127                                        <thead>
128                                                <row>
129                                                        <entry>Lock Name</entry>
130                                                        <entry>Lock Concept</entry>
131                                                </row>
132                                        </thead>
133                                        <tbody>
134                                                <row>
135                                                        <entry>scoped_lock</entry>
136                                                        <entry><link linkend="threads.concepts.ScopedLock">ScopedLock</link></entry>
137                                                </row>
138                                                <row>
139                                                        <entry>scoped_try_lock</entry>
140                                                        <entry><link linkend="threads.concepts.ScopedTryLock">ScopedTryLock</link></entry>
141                                                </row>
142                                        </tbody>
143                                </tgroup>
144                        </informaltable>
145                        </para>
146
147                        <para>The <classname>try_mutex</classname> class uses an
148                        <link linkend="threads.concepts.unspecified-locking-strategy">Unspecified</link>
149                        locking strategy, so attempts to recursively lock a <classname>try_mutex</classname>
150                        object or attempts to unlock one by threads that don't own a lock on it result in
151                        <emphasis role="bold">undefined behavior</emphasis>.
152                        This strategy allows implementations to be as efficient as possible
153                        on any given platform. It is, however, recommended that
154                        implementations include debugging support to detect misuse when
155                        <code>NDEBUG</code> is not defined.</para>
156                       
157                        <para>Like all
158                        <link linkend="threads.concepts.mutex-models">mutex models</link>
159                        in &Boost.Threads;, <classname>try_mutex</classname> leaves the
160                        <link linkend="threads.concepts.sheduling-policies">scheduling policy</link>
161                        as <link linkend="threads.concepts.unspecified-scheduling-policy">Unspecified</link>.
162                        Programmers should make no assumptions about the order in which
163                        waiting threads acquire a lock.</para>
164                </description>
165               
166                <inherit access="private">
167                        <type><classname>boost::noncopyable</classname></type>
168                        <purpose>Exposition only</purpose>
169                </inherit>
170               
171                <typedef name="scoped_lock">
172                        <type><emphasis>implementation-defined</emphasis></type>
173                </typedef>
174               
175                <typedef name="scoped_try_lock">
176                        <type><emphasis>implementation-defined</emphasis></type>
177                </typedef>
178               
179                <constructor>
180                        <effects>Constructs a <classname>try_mutex</classname> object.
181                        </effects>
182                       
183                        <postconditions><code>*this</code> is in an unlocked state.
184                        </postconditions>
185                </constructor>
186
187                <destructor>
188                        <effects>Destroys a <classname>try_mutex</classname> object.
189                        </effects>
190                       
191                        <requires><code>*this</code> is in an unlocked state.</requires>
192                       
193                        <notes><emphasis role="bold">Danger:</emphasis> Destruction of a
194                        locked mutex is a serious programming error resulting in undefined
195                        behavior such as a program crash.</notes>
196                </destructor>
197        </class>
198       
199        <class name="timed_mutex">
200                <purpose>
201                        <para>The <classname>timed_mutex</classname> class is a model of the
202                        <link linkend="threads.concepts.TimedMutex">TimedMutex</link> concept.</para>
203                </purpose>
204               
205                <description>
206                        <para>The <classname>timed_mutex</classname> class is a model of the
207                        <link linkend="threads.concepts.TimedMutex">TimedMutex</link> concept.
208                        It should be used to synchronize access to shared resources using
209                        <link linkend="threads.concepts.unspecified-locking-strategy">Unspecified</link>
210                        locking mechanics.</para>
211
212                        <para>For classes that model related mutex concepts, see
213                        <classname>mutex</classname> and <classname>try_mutex</classname>.</para>
214
215                        <para>For <link linkend="threads.concepts.recursive-locking-strategy">Recursive</link>
216                        locking mechanics, see <classname>recursive_mutex</classname>,
217                        <classname>recursive_try_mutex</classname>, and <classname>recursive_timed_mutex</classname>.
218                        </para>
219                       
220                        <para>The <classname>timed_mutex</classname> class supplies the following typedefs,
221                        which <link linkend="threads.concepts.lock-models">model</link>
222                        the specified locking strategies:
223
224                        <informaltable>
225                                <tgroup cols="2" align="left">
226                                        <thead>
227                                                <row>
228                                                        <entry>Lock Name</entry>
229                                                        <entry>Lock Concept</entry>
230                                                </row>
231                                        </thead>
232                                        <tbody>
233                                                <row>
234                                                        <entry>scoped_lock</entry>
235                                                        <entry><link linkend="threads.concepts.ScopedLock">ScopedLock</link></entry>
236                                                </row>
237                                                <row>
238                                                        <entry>scoped_try_lock</entry>
239                                                        <entry><link linkend="threads.concepts.ScopedTryLock">ScopedTryLock</link></entry>
240                                                </row>
241                                                <row>
242                                                        <entry>scoped_timed_lock</entry>
243                                                        <entry><link linkend="threads.concepts.ScopedTimedLock">ScopedTimedLock</link></entry>
244                                                </row>
245                                        </tbody>
246                                </tgroup>
247                        </informaltable>
248                        </para>
249
250                        <para>The <classname>timed_mutex</classname> class uses an
251                        <link linkend="threads.concepts.unspecified-locking-strategy">Unspecified</link>
252                        locking strategy, so attempts to recursively lock a <classname>timed_mutex</classname>
253                        object or attempts to unlock one by threads that don't own a lock on it result in
254                        <emphasis role="bold">undefined behavior</emphasis>.
255                        This strategy allows implementations to be as efficient as possible
256                        on any given platform. It is, however, recommended that
257                        implementations include debugging support to detect misuse when
258                        <code>NDEBUG</code> is not defined.</para>
259                       
260                        <para>Like all
261                        <link linkend="threads.concepts.mutex-models">mutex models</link>
262                        in  &Boost.Threads;, <classname>timed_mutex</classname> leaves the
263                        <link linkend="threads.concepts.sheduling-policies">scheduling policy</link>
264                        as <link linkend="threads.concepts.unspecified-scheduling-policy">Unspecified</link>.
265                        Programmers should make no assumptions about the order in which
266                        waiting threads acquire a lock.</para>
267                </description>
268               
269                <inherit access="private">
270                        <type><classname>boost::noncopyable</classname></type>
271                        <purpose>Exposition only</purpose>
272                </inherit>
273               
274                <typedef name="scoped_lock">
275                        <type><emphasis>implementation-defined</emphasis></type>
276                </typedef>
277               
278                <typedef name="scoped_try_lock">
279                        <type><emphasis>implementation-defined</emphasis></type>
280                </typedef>
281               
282                <typedef name="scoped_timed_lock">
283                        <type><emphasis>implementation-defined</emphasis></type>
284                </typedef>
285               
286                <constructor>
287                        <effects>Constructs a <classname>timed_mutex</classname> object.
288                        </effects>
289                       
290                        <postconditions><code>*this</code> is in an unlocked state.
291                        </postconditions>
292                </constructor>
293
294                <destructor>
295                        <effects>Destroys a <classname>timed_mutex</classname> object.</effects>
296                       
297                        <requires><code>*this</code> is in an unlocked state.</requires>
298                       
299                        <notes><emphasis role="bold">Danger:</emphasis> Destruction of a
300                        locked mutex is a serious programming error resulting in undefined
301                        behavior such as a program crash.</notes>
302                </destructor>
303        </class>
304  </namespace>
305</header>
Note: See TracBrowser for help on using the repository browser.