source: rtems/doc/posix_users/mutex.t @ 6449498

4.104.114.84.95
Last change on this file since 6449498 was 6449498, checked in by Joel Sherrill <joel.sherrill@…>, on Jan 17, 2002 at 9:47:47 PM

2001-01-17 Joel Sherrill <joel@…>

  • SUPPORT, LICENSE: New files.
  • Numerous files touched as part of merging the 4.5 branch onto the mainline development trunk and ensuring that the script that cuts snapshots and releases works on the documentation.
  • Property mode set to 100644
File size: 13.7 KB
Line 
1@c
2@c COPYRIGHT (c) 1988-2002.
3@c On-Line Applications Research Corporation (OAR).
4@c All rights reserved.
5@c
6@c $Id$
7@c
8
9@chapter Mutex Manager
10
11@section Introduction
12
13The mutex manager implements the functionality required of the mutex
14manager as defined by POSIX 1003.1b-1996. This standard requires that
15a compliant operating system provide the facilties to ensure that
16threads can operate with mutual exclusion from one another and
17defines the API that must be provided.
18
19The services provided by the mutex manager are:
20
21@itemize @bullet
22@item @code{pthread_mutexattr_init} - Initialize a Mutex Attribute Set
23@item @code{pthread_mutexattr_destroy} - Destroy a Mutex Attribute Set
24@item @code{pthread_mutexattr_setprotocol} - Set the Blocking Protocol
25@item @code{pthread_mutexattr_getprotocol} - Get the Blocking Protocol
26@item @code{pthread_mutexattr_setprioceiling} - Set the Priority Ceiling
27@item @code{pthread_mutexattr_getprioceiling} - Get the Priority Ceiling
28@item @code{pthread_mutexattr_setpshared} - Set the Visibility
29@item @code{pthread_mutexattr_getpshared} - Get the Visibility
30@item @code{pthread_mutex_init} - Initialize a Mutex
31@item @code{pthread_mutex_destroy} - Destroy a Mutex
32@item @code{pthread_mutex_lock} - Lock a Mutex
33@item @code{pthread_mutex_trylock} - Poll to Lock a Mutex
34@item @code{pthread_mutex_timedlock} - Lock a Mutex with Timeout
35@item @code{pthread_mutex_unlock} - Unlock a Mutex
36@item @code{pthread_mutex_setprioceiling} - Dynamically Set the Priority Ceiling
37@item @code{pthread_mutex_getprioceiling} - Dynamically Get the Priority Ceiling
38@end itemize
39
40@section Background
41
42@subsection Mutex Attributes
43
44Mutex attributes are utilized only at mutex creation time. A mutex
45attribute structure may be initialized and passed as an argument to
46the @code{mutex_init} routine. Note that the priority ceiling of
47a mutex may be set at run-time.
48
49@table @b
50@item blocking protcol
51is the XXX
52
53@item priority ceiling
54is the XXX
55
56@item pshared
57is the XXX
58
59@end table
60
61@subsection PTHREAD_MUTEX_INITIALIZER
62
63This is a special value that a variable of type @code{pthread_mutex_t}
64may be statically initialized to as shown below:
65
66@example
67pthread_mutex_t my_mutex = PTHREAD_MUTEX_INITIALIZER;
68@end example
69
70This indicates that @code{my_mutex} will be automatically initialized
71by an implicit call to @code{pthread_mutex_init} the first time
72the mutex is used.
73
74Note that the mutex will be initialized with default attributes.
75
76@section Operations
77
78There is currently no text in this section.
79
80@section Services
81
82This section details the mutex manager's services.
83A subsection is dedicated to each of this manager's services
84and describes the calling sequence, related constants, usage,
85and status codes.
86
87@c
88@c
89@c
90@page
91@subsection pthread_mutexattr_init - Initialize a Mutex Attribute Set
92
93@findex pthread_mutexattr_init
94@cindex  initialize a mutex attribute set
95
96@subheading CALLING SEQUENCE:
97
98@example
99#include <pthread.h>
100
101int pthread_mutexattr_init(
102  pthread_mutexattr_t *attr
103);
104@end example
105
106@subheading STATUS CODES:
107
108@table @b
109@item EINVAL
110The attribute pointer argument is invalid.
111
112@end table
113
114@subheading DESCRIPTION:
115
116The @code{pthread_mutexattr_init} routine initializes the mutex attributes
117object specified by @code{attr} with the default value for all of the
118individual attributes.
119
120@subheading NOTES:
121
122XXX insert list of default attributes here.
123
124@c
125@c
126@c
127@page
128@subsection pthread_mutexattr_destroy - Destroy a Mutex Attribute Set
129
130@findex pthread_mutexattr_destroy
131@cindex  destroy a mutex attribute set
132
133@subheading CALLING SEQUENCE:
134
135@example
136#include <pthread.h>
137
138int pthread_mutexattr_destroy(
139  pthread_mutexattr_t *attr
140);
141@end example
142
143@subheading STATUS CODES:
144
145@table @b
146@item EINVAL
147The attribute pointer argument is invalid.
148
149@item EINVAL
150The attribute set is not initialized.
151
152@end table
153
154@subheading DESCRIPTION:
155
156The @code{pthread_mutex_attr_destroy} routine is used to destroy a mutex
157attributes object. The behavior of using an attributes object after
158it is destroyed is implementation dependent.
159
160@subheading NOTES:
161
162NONE
163
164@c
165@c
166@c
167@page
168@subsection pthread_mutexattr_setprotocol - Set the Blocking Protocol
169
170@findex pthread_mutexattr_setprotocol
171@cindex  set the blocking protocol
172
173@subheading CALLING SEQUENCE:
174
175@example
176#include <pthread.h>
177
178int pthread_mutexattr_setprotocol(
179  pthread_mutexattr_t *attr,
180  int                  protocol
181);
182@end example
183
184@subheading STATUS CODES:
185
186@table @b
187@item EINVAL
188The attribute pointer argument is invalid.
189
190@item EINVAL
191The attribute set is not initialized.
192
193@item EINVAL
194The protocol argument is invalid.
195
196@end table
197
198@subheading DESCRIPTION:
199
200The @code{pthread_mutexattr_setprotocol} routine is used to set value of the
201@code{protocol} attribute. This attribute controls the order in which
202threads waiting on this mutex will receive it.
203
204The @code{protocol} can be one of the following:
205
206@table @b
207
208@item @code{PTHREAD_PRIO_NONE}
209in which case blocking order is FIFO.
210
211@item @code{PTHREAD_PRIO_INHERIT}
212in which case blocking order is priority with the priority inheritance
213protocol in effect.
214
215@item @code{PTHREAD_PRIO_PROTECT}
216in which case blocking order is priority with the priority ceiling
217protocol in effect.
218
219@end table
220
221@subheading NOTES:
222
223There is currently no way to get simple priority blocking ordering
224with POSIX mutexes even though this could easily by supported by RTEMS.
225
226@c
227@c
228@c
229@page
230@subsection pthread_mutexattr_getprotocol - Get the Blocking Protocol
231
232@findex pthread_mutexattr_getprotocol
233@cindex  get the blocking protocol
234
235@subheading CALLING SEQUENCE:
236
237@example
238#include <pthread.h>
239
240int pthread_mutexattr_getprotocol(
241  pthread_mutexattr_t *attr,
242  int                 *protocol
243);
244@end example
245
246@subheading STATUS CODES:
247
248@table @b
249@item EINVAL
250The attribute pointer argument is invalid.
251
252@item EINVAL
253The attribute set is not initialized.
254
255@item EINVAL
256The protocol pointer argument is invalid.
257
258@end table
259
260@subheading DESCRIPTION:
261
262The @code{pthread_mutexattr_getprotocol} routine is used to obtain
263the value of the @code{protocol} attribute. This attribute controls
264the order in which threads waiting on this mutex will receive it.
265
266@subheading NOTES:
267
268NONE
269
270@c
271@c
272@c
273@page
274@subsection pthread_mutexattr_setprioceiling - Set the Priority Ceiling
275
276@findex pthread_mutexattr_setprioceiling
277@cindex  set the priority ceiling
278
279@subheading CALLING SEQUENCE:
280
281@example
282#include <pthread.h>
283
284int pthread_mutexattr_setprioceiling(
285  pthread_mutexattr_t *attr,
286  int                  prioceiling
287);
288@end example
289
290@subheading STATUS CODES:
291
292@table @b
293@item EINVAL
294The attribute pointer argument is invalid.
295
296@item EINVAL
297The attribute set is not initialized.
298
299@item EINVAL
300The prioceiling argument is invalid.
301
302@end table
303
304@subheading DESCRIPTION:
305
306The @code{pthread_mutexattr_setprioceiling} routine is used to set value of the
307@code{prioceiling} attribute. This attribute specifies the priority that
308is the ceiling for threads obtaining this mutex. Any task obtaining this
309mutex may not be of greater priority that the ceiling. If it is of lower
310priority, then its priority will be elevated to @code{prioceiling}.
311
312@subheading NOTES:
313
314NONE
315
316@c
317@c
318@c
319@page
320@subsection pthread_mutexattr_getprioceiling - Get the Priority Ceiling
321
322@findex pthread_mutexattr_getprioceiling
323@cindex  get the priority ceiling
324
325@subheading CALLING SEQUENCE:
326
327@example
328#include <pthread.h>
329
330int pthread_mutexattr_getprioceiling(
331  const pthread_mutexattr_t *attr,
332  int                       *prioceiling
333);
334@end example
335
336@subheading STATUS CODES:
337
338@table @b
339@item EINVAL
340The attribute pointer argument is invalid.
341
342@item EINVAL
343The attribute set is not initialized.
344
345@item EINVAL
346The prioceiling pointer argument is invalid.
347
348@end table
349
350@subheading DESCRIPTION:
351
352The @code{pthread_mutexattr_getprioceiling} routine is used to obtain the
353value of the @code{prioceiling} attribute. This attribute specifies the
354priority ceiling for this mutex.
355
356
357@subheading NOTES:
358
359
360NONE
361@c
362@c
363@c
364@page
365@subsection pthread_mutexattr_setpshared - Set the Visibility
366
367@findex pthread_mutexattr_setpshared
368@cindex  set the visibility
369
370@subheading CALLING SEQUENCE:
371
372@example
373#include <pthread.h>
374
375int pthread_mutexattr_setpshared(
376  pthread_mutexattr_t *attr,
377  int                  pshared
378);
379@end example
380
381@subheading STATUS CODES:
382
383@table @b
384@item EINVAL
385The attribute pointer argument is invalid.
386
387@item EINVAL
388The attribute set is not initialized.
389
390@item EINVAL
391The pshared argument is invalid.
392
393@end table
394
395@subheading DESCRIPTION:
396
397@subheading NOTES:
398
399@c
400@c
401@c
402@page
403@subsection pthread_mutexattr_getpshared - Get the Visibility
404
405@findex pthread_mutexattr_getpshared
406@cindex  get the visibility
407
408@subheading CALLING SEQUENCE:
409
410@example
411#include <pthread.h>
412
413int pthread_mutexattr_getpshared(
414  const pthread_mutexattr_t *attr,
415  int                       *pshared
416);
417@end example
418
419@subheading STATUS CODES:
420
421@table @b
422@item EINVAL
423The attribute pointer argument is invalid.
424
425@item EINVAL
426The attribute set is not initialized.
427
428@item EINVAL
429The pshared pointer argument is invalid.
430
431@end table
432
433@subheading DESCRIPTION:
434
435@subheading NOTES:
436
437@c
438@c
439@c
440@page
441@subsection pthread_mutex_init - Initialize a Mutex
442
443@findex pthread_mutex_init
444@cindex  initialize a mutex
445
446@subheading CALLING SEQUENCE:
447
448@example
449#include <pthread.h>
450
451int pthread_mutex_init(
452  pthread_mutex_t           *mutex,
453  const pthread_mutexattr_t *attr
454);
455@end example
456
457@subheading STATUS CODES:
458
459@table @b
460@item EINVAL
461The attribute set is not initialized.
462
463@item EINVAL
464The specified protocol is invalid.
465
466@item EAGAIN
467The system lacked the necessary resources to initialize another mutex.
468
469@item ENOMEM
470Insufficient memory exists to initialize the mutex.
471
472@item EBUSY
473Attempted to reinialize the object reference by mutex, a previously
474initialized, but not yet destroyed.
475
476@end table
477
478@subheading DESCRIPTION:
479
480@subheading NOTES:
481
482@c
483@c
484@c
485@page
486@subsection pthread_mutex_destroy - Destroy a Mutex
487
488@findex pthread_mutex_destroy
489@cindex  destroy a mutex
490
491@subheading CALLING SEQUENCE:
492
493@example
494#include <pthread.h>
495
496int pthread_mutex_destroy(
497  pthread_mutex_t *mutex
498);
499@end example
500
501@subheading STATUS CODES:
502
503@table @b
504@item EINVAL
505The specified mutex is invalid.
506
507@item EBUSY
508Attempted to destroy the object reference by mutex, while it is locked or
509referenced by another thread.
510
511@end table
512
513@subheading DESCRIPTION:
514
515@subheading NOTES:
516
517@c
518@c
519@c
520@page
521@subsection pthread_mutex_lock - Lock a Mutex
522
523@findex pthread_mutex_lock
524@cindex  lock a mutex
525
526@subheading CALLING SEQUENCE:
527
528@example
529#include <pthread.h>
530
531int pthread_mutex_lock(
532  pthread_mutex_t *mutex
533);
534@end example
535
536@subheading STATUS CODES:
537
538@table @b
539@item EINVAL
540The specified mutex is invalid.
541
542@item EINVAL
543The mutex has the protocol attribute of PTHREAD_PRIO_PROTECT and the
544priority of the calling thread is higher than the current priority
545ceiling.
546
547@item EDEADLK
548The current thread already owns the mutex.
549
550@end table
551
552@subheading DESCRIPTION:
553
554@subheading NOTES:
555
556@c
557@c
558@c
559@page
560@subsection pthread_mutex_trylock - Poll to Lock a Mutex
561
562@findex pthread_mutex_trylock
563@cindex  poll to lock a mutex
564
565@subheading CALLING SEQUENCE:
566
567@example
568#include <pthread.h>
569
570int pthread_mutex_trylock(
571  pthread_mutex_t *mutex
572);
573@end example
574
575@subheading STATUS CODES:
576
577@table @b
578@item EINVAL
579The specified mutex is invalid.
580
581@item EINVAL
582The mutex has the protocol attribute of PTHREAD_PRIO_PROTECT and the
583priority of the calling thread is higher than the current priority
584ceiling.
585
586@item EDEADLK
587The current thread already owns the mutex.
588
589@end table
590
591@subheading DESCRIPTION:
592
593@subheading NOTES:
594
595@c
596@c
597@c
598@page
599@subsection pthread_mutex_timedlock - Lock a Mutex with Timeout
600
601@findex pthread_mutex_timedlock
602@cindex  lock a mutex with timeout
603
604@subheading CALLING SEQUENCE:
605
606@example
607#include <pthread.h>
608#include <time.h>
609
610int pthread_mutex_timedlock(
611  pthread_mutex_t       *mutex,
612  const struct timespec *timeout
613);
614@end example
615
616@subheading STATUS CODES:
617
618@table @b
619@item EINVAL
620The specified mutex is invalid.
621
622@item EINVAL
623The nanoseconds field of timeout is invalid.
624
625@item EINVAL
626The mutex has the protocol attribute of PTHREAD_PRIO_PROTECT and the
627priority of the calling thread is higher than the current priority
628ceiling.
629
630@item EDEADLK
631The current thread already owns the mutex.
632
633@end table
634
635@subheading DESCRIPTION:
636
637@subheading NOTES:
638
639
640@c
641@c
642@c
643@page
644@subsection pthread_mutex_unlock - Unlock a Mutex
645
646@findex pthread_mutex_unlock
647@cindex  unlock a mutex
648
649@subheading CALLING SEQUENCE:
650
651@example
652#include <pthread.h>
653
654int pthread_mutex_unlock(
655  pthread_mutex_t *mutex
656);
657@end example
658
659@subheading STATUS CODES:
660
661@table @b
662@item EINVAL
663The specified mutex is invalid.
664
665@end table
666
667@subheading DESCRIPTION:
668
669@subheading NOTES:
670
671@c
672@c
673@c
674@page
675@subsection pthread_mutex_setprioceiling - Dynamically Set the Priority Ceiling
676
677@findex pthread_mutex_setprioceiling
678@cindex  dynamically set the priority ceiling
679
680@subheading CALLING SEQUENCE:
681
682@example
683#include <pthread.h>
684
685int pthread_mutex_setprioceiling(
686  pthread_mutex_t *mutex,
687  int              prioceiling,
688  int             *oldceiling
689);
690@end example
691
692@subheading STATUS CODES:
693
694@table @b
695@item EINVAL
696The oldceiling pointer parameter is invalid.
697
698@item EINVAL
699The prioceiling parameter is an invalid priority.
700
701@item EINVAL
702The specified mutex is invalid.
703
704@end table
705
706@subheading DESCRIPTION:
707
708@subheading NOTES:
709
710@c
711@c
712@c
713@page
714@subsection pthread_mutex_getprioceiling - Get the Current Priority Ceiling
715
716@findex pthread_mutex_getprioceiling
717@cindex  get the current priority ceiling
718
719@subheading CALLING SEQUENCE:
720
721@example
722#include <pthread.h>
723
724int pthread_mutex_getprioceiling(
725  pthread_mutex_t *mutex,
726  int             *prioceiling
727);
728@end example
729
730@subheading STATUS CODES:
731
732@table @b
733@item EINVAL
734The prioceiling pointer parameter is invalid.
735
736@item EINVAL
737The specified mutex is invalid.
738
739@end table
740
741@subheading DESCRIPTION:
742
743@subheading NOTES:
744
Note: See TracBrowser for help on using the repository browser.