Planet

navi

home

PPS

about

screenshots

download

development

forum

Context Navigation

source: downloads/boost_1_34_1/libs/thread/doc/mutex-ref.xml @ 29

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

Note: See TracBrowser for help on using the repository browser.

Download in other formats: