Changeset 98b9a3b in rtems


Ignore:
Timestamp:
Dec 5, 2013, 3:16:11 PM (6 years ago)
Author:
Sahil Patnayakuni <sahil.patnayakuni@…>
Branches:
4.11, master
Children:
262e250
Parents:
25026906
git-author:
Sahil Patnayakuni <sahil.patnayakuni@…> (12/05/13 15:16:11)
git-committer:
Gedare Bloom <gedare@…> (12/05/13 15:16:11)
Message:

doc/posix_users: add notes and descriptions for pthread_key functions

File:
1 edited

Legend:

Unmodified
Added
Removed
  • doc/posix_users/key.t

    r25026906 r98b9a3b  
    88@section Introduction
    99
    10 The key manager ...
     10The key manager allows for the creation and deletion of Data keys
     11specific to threads.
    1112
    1213The directives provided by the key manager are:
     
    6263@end table
    6364
     65@subheading DESCRIPTION
     66The pthread_key_create() function shall create a thread-specific data
     67key visible to all threads in the process. Key values provided by
     68pthread_key_create() are opaque objects used to locate thread-specific
     69data. Although the same key value may be used by different threads, the
     70values bound to the key by pthread_setspecific() are maintained on a
     71per-thread basis and persist for the life of the calling thread.
     72
     73Upon key creation, the value NULL shall be associated with the new key
     74in all active threads. Upon thread creation, the value NULL shall be
     75associated with all defined keys in the new thread.
     76
     77@subheading NOTES
     78An optional destructor function may be associated with each key value.
     79At thread exit, if a key value has a non-NULL destructor pointer, and
     80the thread has a non-NULL value associated with that key, the value of
     81the key is set to NULL, and then the function pointed to is called with
     82the previously associated value as its sole argument. The order of
     83destructor calls is unspecified if more than one destructor exists for
     84a thread when it exits.
     85
    6486@c
    6587@c
     
    7496
    7597int pthread_key_delete(
    76 pthread_key_t key,
    77 );
     98pthread_key_t key);
    7899@end example
    79100
     
    87108
    88109@subheading DESCRIPTION:
     110The pthread_key_delete() function shall delete a thread-specific data key
     111previously returned by pthread_key_create(). The thread-specific data
     112values associated with key need not be NULL at the time pthread_key_delete()
     113is called. It is the responsibility of the application to free any
     114application storage or perform any cleanup actions for data structures related
     115to the deleted key or associated thread-specific data in any
     116threads; this cleanup can be done either before or after
     117pthread_key_delete() is called. Any attempt to use key following the call to
     118pthread_key_delete() results in undefined behavior.
    89119
    90120@subheading NOTES:
     121The pthread_key_delete() function shall be callable from within
     122destructor functions. No destructor functions shall be invoked by
     123pthread_key_delete(). Any destructor function that may have been
     124associated with key shall no longer be called upon thread exit.
     125
    91126
    92127@c
     
    115150
    116151@subheading DESCRIPTION:
    117 
    118 @subheading NOTES:
     152The pthread_setspecific() function shall associate a thread-specific value
     153with a key obtained via a previous call to pthread_key_create().
     154Different threads may bind different values to the same key. These values
     155are typically pointers to blocks of dynamically allocated memory that
     156have been reserved for use by the calling thread.
     157       
     158@subheading NOTES:     
     159The effect of calling pthread_setspecific() with a key value not obtained
     160from pthread_key_create() or after key has
     161been deleted with pthread_key_delete() is undefined.
     162
     163pthread_setspecific() may be called from a thread-specific data
     164destructor function. Calling pthread_setspecific() from a thread-specific
     165data destructor routine may result either in lost storage (after at least
     166PTHREAD_DESTRUCTOR_ITERATIONS attempts at destruction) or in an infinite loop.
     167
    119168
    120169@c
     
    145194
    146195@subheading DESCRIPTION:
     196The pthread_getspecific() function shall return the value currently bound to
     197the specified key on behalf of the calling thread.
    147198
    148199@subheading NOTES:
    149 
     200The effect of calling pthread_getspecific() with a key value not obtained from
     201pthread_key_create() or after key has
     202been deleted with pthread_key_delete() is undefined.
     203
     204pthread_getspecific() may be called from a thread-specific data destructor
     205function. A call to pthread_getspecific() for the thread-specific data key
     206being destroyed shall return the value NULL, unless the value is changed
     207(after the destructor starts) by a call to pthread_setspecific().
     208
Note: See TracChangeset for help on using the changeset viewer.