source: rtems/doc/posix_users/mutex.t @ 9b4f75e

Last change on this file since 9b4f75e was 9b4f75e, checked in by Joel Sherrill <joel.sherrill@…>, on 07/24/08 at 20:44:47

2008-07-24 Joel Sherrill <joel.sherrill@…>

PR 1291/cpukit

  • posix_users/mutex.t, posix_users/semaphores.t: Update tests to reflect changes required by POSIX blocking calls sometimes taking relative not absolute time.
  • Property mode set to 100644
File size: 13.8 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@item ETIMEDOUT
634The calling thread was unable to obtain the mutex within the specified
635timeout period.
636
637@end table
638
639@subheading DESCRIPTION:
640
641@subheading NOTES:
642
643
644@c
645@c
646@c
647@page
648@subsection pthread_mutex_unlock - Unlock a Mutex
649
650@findex pthread_mutex_unlock
651@cindex  unlock a mutex
652
653@subheading CALLING SEQUENCE:
654
655@example
656#include <pthread.h>
657
658int pthread_mutex_unlock(
659  pthread_mutex_t *mutex
660);
661@end example
662
663@subheading STATUS CODES:
664
665@table @b
666@item EINVAL
667The specified mutex is invalid.
668
669@end table
670
671@subheading DESCRIPTION:
672
673@subheading NOTES:
674
675@c
676@c
677@c
678@page
679@subsection pthread_mutex_setprioceiling - Dynamically Set the Priority Ceiling
680
681@findex pthread_mutex_setprioceiling
682@cindex  dynamically set the priority ceiling
683
684@subheading CALLING SEQUENCE:
685
686@example
687#include <pthread.h>
688
689int pthread_mutex_setprioceiling(
690  pthread_mutex_t *mutex,
691  int              prioceiling,
692  int             *oldceiling
693);
694@end example
695
696@subheading STATUS CODES:
697
698@table @b
699@item EINVAL
700The oldceiling pointer parameter is invalid.
701
702@item EINVAL
703The prioceiling parameter is an invalid priority.
704
705@item EINVAL
706The specified mutex is invalid.
707
708@end table
709
710@subheading DESCRIPTION:
711
712@subheading NOTES:
713
714@c
715@c
716@c
717@page
718@subsection pthread_mutex_getprioceiling - Get the Current Priority Ceiling
719
720@findex pthread_mutex_getprioceiling
721@cindex  get the current priority ceiling
722
723@subheading CALLING SEQUENCE:
724
725@example
726#include <pthread.h>
727
728int pthread_mutex_getprioceiling(
729  pthread_mutex_t *mutex,
730  int             *prioceiling
731);
732@end example
733
734@subheading STATUS CODES:
735
736@table @b
737@item EINVAL
738The prioceiling pointer parameter is invalid.
739
740@item EINVAL
741The specified mutex is invalid.
742
743@end table
744
745@subheading DESCRIPTION:
746
747@subheading NOTES:
748
Note: See TracBrowser for help on using the repository browser.