Changeset 56853af in rtems


Ignore:
Timestamp:
Jun 15, 1999, 12:32:19 AM (22 years ago)
Author:
Joel Sherrill <joel.sherrill@…>
Branches:
4.10, 4.11, 4.8, 4.9, 5, master
Children:
1b67be71
Parents:
d48ea69
Message:

Some stuff added.

File:
1 edited

Legend:

Unmodified
Added
Removed

  • doc/posix_users/mutex.t

    rd48ea69 r56853af  
    1111@section Introduction
    1212
    13 The mutex manager ...
    14 
    15 The directives provided by the mutex manager are:
     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:
    1620
    1721@itemize @bullet
    18 @item @code{pthread_mutexattr_init} -
    19 @item @code{pthread_mutexattr_destroy} -
    20 @item @code{pthread_mutexattr_setprotocol} -
    21 @item @code{pthread_mutexattr_getprotocol} -
    22 @item @code{pthread_mutexattr_setprioceiling} -
    23 @item @code{pthread_mutexattr_getprioceiling} -
    24 @item @code{pthread_mutexattr_setpshared} -
    25 @item @code{pthread_mutexattr_getpshared} -
    26 @item @code{pthread_mutex_init} -
    27 @item @code{pthread_mutex_destroy} -
    28 @item @code{pthread_mutex_lock} -
    29 @item @code{pthread_mutex_trylock} -
    30 @item @code{pthread_mutex_timedlock} -
    31 @item @code{pthread_mutex_unlock} -
    32 @item @code{pthread_mutex_setprioceiling} -
    33 @item @code{pthread_mutex_getprioceiling} -
     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
    3438@end itemize
    3539
    3640@section Background
    3741
     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
    3878There is currently no text in this section.
    3979
    40 @section Operations
    41 
    42 There is currently no text in this section.
    43 
    44 @section Directives
    45 
    46 This section details the mutex manager's directives.
    47 A subsection is dedicated to each of this manager's directives
     80@section Services
     81
     82This section details the mutex manager's services.
     83A subsection is dedicated to each of this manager's services
    4884and describes the calling sequence, related constants, usage,
    4985and status codes.
    5086
    5187@page
    52 @subsection pthread_mutexattr_init
     88@subsection pthread_mutexattr_init - Initialize a Mutex Attribute Set
    5389
    5490@subheading CALLING SEQUENCE:
    … …  
    72108@subheading DESCRIPTION:
    73109
    74 @subheading NOTES:
    75 
    76 @page
    77 @subsection pthread_mutexattr_destroy
     110The @code{pthread_mutexattr_init} routine initializes the mutex attributes
     111object specified by @code{attr} with the default value for all of the
     112individual attributes.
     113
     114@subheading NOTES:
     115
     116XXX insert list of default attributes here.
     117
     118@page
     119@subsection pthread_mutexattr_destroy - Destroy a Mutex Attribute Set
    78120
    79121@subheading CALLING SEQUENCE:
    … …  
    100142@subheading DESCRIPTION:
    101143
    102 @subheading NOTES:
    103 
    104 @page
    105 @subsection pthread_mutexattr_setprotocol
     144The @code{pthread_mutex_attr_destroy} routine is used to destroy a mutex
     145attributes object.  The behavior of using an attributes object after
     146it is destroyed is implementation dependent.
     147
     148@subheading NOTES:
     149
     150NONE
     151
     152@page
     153@subsection pthread_mutexattr_setprotocol - Set the Blocking Protocol
    106154
    107155@subheading CALLING SEQUENCE:
    … …  
    132180@subheading DESCRIPTION:
    133181
    134 @subheading NOTES:
    135 
    136 @page
    137 @subsection pthread_mutexattr_getprotocol
     182The @code{pthread_mutexattr_setprotocol} routine is used to set value of the
     183@code{protocol} attribute.  This attribute controls the order in which
     184threads waiting on this mutex will receive it.
     185
     186The @code{protocol} can be one of the following:
     187
     188@table @b
     189
     190@item @code{PTHREAD_PRIO_NONE}
     191in which case blocking order is FIFO.
     192
     193@item @code{PTHREAD_PRIO_INHERIT}
     194in which case blocking order is  priority with the priority inheritance
     195protocol in effect.
     196
     197@item @code{PTHREAD_PRIO_PROTECT}
     198in which case blocking order is  priority with the priority ceiling
     199protocol in effect.
     200
     201@end table
     202
     203@subheading NOTES:
     204
     205There is currently no way to get simple priority blocking ordering
     206with POSIX mutexes even though this could easily by supported by RTEMS.
     207
     208@page
     209@subsection pthread_mutexattr_getprotocol - Get the Blocking Protocol
    138210 
    139211@subheading CALLING SEQUENCE:
    … …  
    164236@subheading DESCRIPTION:
    165237 
    166 @subheading NOTES:
    167 
    168 @page
    169 @subsection pthread_mutexattr_setprioceiling
     238The @code{pthread_mutexattr_getprotocol} routine is used to obtain
     239the value of the @code{protocol} attribute.  This attribute controls
     240the order in which threads waiting on this mutex will receive it.
     241
     242@subheading NOTES:
     243
     244NONE
     245
     246@page
     247@subsection pthread_mutexattr_setprioceiling - Set the Priority Ceiling
    170248
    171249@subheading CALLING SEQUENCE:
    … …  
    196274@subheading DESCRIPTION:
    197275
    198 @subheading NOTES:
    199 
    200 @page
    201 @subsection pthread_mutexattr_getprioceiling
     276The @code{pthread_mutexattr_setprioceiling} routine is used to set value of the
     277@code{prioceiling} attribute.  This attribute specifies the priority that
     278is the ceiling for threads obtaining this mutex.  Any task obtaining this
     279mutex may not be of greater priority that the ceiling.  If it is of lower
     280priority, then its priority will be elevated to @code{prioceiling}. 
     281
     282@subheading NOTES:
     283
     284NONE
     285
     286@page
     287@subsection pthread_mutexattr_getprioceiling - Get the Priority Ceiling
    202288
    203289@subheading CALLING SEQUENCE:
    … …  
    228314@subheading DESCRIPTION:
    229315
    230 @subheading NOTES:
    231 
    232 @page
    233 @subsection pthread_mutexattr_setpshared
     316The @code{pthread_mutexattr_getprioceiling} routine is used to obtain the
     317value of the @code{prioceiling} attribute.  This attribute specifies the
     318priority ceiling for this mutex.
     319
     320
     321@subheading NOTES:
     322
     323
     324NONE
     325@page
     326@subsection pthread_mutexattr_setpshared - Set the Visibility
    234327
    235328@subheading CALLING SEQUENCE:
    … …  
    263356
    264357@page
    265 @subsection pthread_mutexattr_getpshared
     358@subsection pthread_mutexattr_getpshared - Get the Visibility
    266359
    267360@subheading CALLING SEQUENCE:
    … …  
    295388
    296389@page
    297 @subsection pthread_mutex_init
     390@subsection pthread_mutex_init - Initialize a Mutex
    298391
    299392@subheading CALLING SEQUENCE:
    … …  
    334427
    335428@page
    336 @subsection pthread_mutex_destroy
     429@subsection pthread_mutex_destroy - Destroy a Mutex
    337430
    338431@subheading CALLING SEQUENCE:
    … …  
    363456
    364457@page
    365 @subsection pthread_mutex_lock
     458@subsection pthread_mutex_lock - Lock a Mutex
    366459
    367460@subheading CALLING SEQUENCE:
    … …  
    396489
    397490@page
    398 @subsection pthread_mutex_trylock
     491@subsection pthread_mutex_trylock - Poll to Lock a Mutex
    399492 
    400493@subheading CALLING SEQUENCE:
    … …  
    429522 
    430523@page
    431 @subsection pthread_mutex_timedlock
     524@subsection pthread_mutex_timedlock - Lock a Mutex with Timeout
    432525 
    433526@subheading CALLING SEQUENCE:
    … …  
    468561
    469562@page
    470 @subsection pthread_mutex_unlock
     563@subsection pthread_mutex_unlock - Unlock a Mutex
    471564
    472565@subheading CALLING SEQUENCE:
    … …  
    493586
    494587@page
    495 @subsection pthread_mutex_setprioceiling
     588@subsection pthread_mutex_setprioceiling - Dynamically Set the Priority Ceiling
    496589
    497590@subheading CALLING SEQUENCE:
    … …  
    526619
    527620@page
    528 @subsection pthread_mutex_getprioceiling
     621@subsection pthread_mutex_getprioceiling - Get the Current Priority Ceiling
    529622
    530623@subheading CALLING SEQUENCE:
Note: See TracChangeset for help on using the changeset viewer.