[rtems commit] doc/posix_users: add notes and descriptions for pthread_key functions

[Gedare Bloom]

Module:    rtems
Branch:    master
Commit:    98b9a3b5cb9f28b911e6b4dd19453a7cffa529e3
Changeset: http://git.rtems.org/rtems/commit/?id=98b9a3b5cb9f28b911e6b4dd19453a7cffa529e3

Author:    Sahil Patnayakuni <sahil.patnayakuni at gmail.com>
Date:      Thu Dec  5 10:16:11 2013 -0500

doc/posix_users: add notes and descriptions for pthread_key functions

---

 doc/posix_users/key.t |   67 ++++++++++++++++++++++++++++++++++++++++++++++---
 1 files changed, 63 insertions(+), 4 deletions(-)

diff --git a/doc/posix_users/key.t b/doc/posix_users/key.t
index 28bc7f5..dd7a83d 100644
--- a/doc/posix_users/key.t
+++ b/doc/posix_users/key.t
@@ -7,7 +7,8 @@
 
 @section Introduction
 
-The key manager ...
+The key manager allows for the creation and deletion of Data keys
+specific to threads.
 
 The directives provided by the key manager are:
 
@@ -61,6 +62,27 @@ Insufficient memory exists to create the key.
 
 @end table
 
+ at subheading DESCRIPTION
+The pthread_key_create() function shall create a thread-specific data
+key visible to all threads in the process. Key values provided by
+pthread_key_create() are opaque objects used to locate thread-specific
+data. Although the same key value may be used by different threads, the
+values bound to the key by pthread_setspecific() are maintained on a
+per-thread basis and persist for the life of the calling thread.
+
+Upon key creation, the value NULL shall be associated with the new key
+in all active threads. Upon thread creation, the value NULL shall be
+associated with all defined keys in the new thread.
+
+ at subheading NOTES
+An optional destructor function may be associated with each key value.
+At thread exit, if a key value has a non-NULL destructor pointer, and
+the thread has a non-NULL value associated with that key, the value of
+the key is set to NULL, and then the function pointed to is called with
+the previously associated value as its sole argument. The order of
+destructor calls is unspecified if more than one destructor exists for
+a thread when it exits.
+
 @c
 @c
 @c
@@ -73,8 +95,7 @@ Insufficient memory exists to create the key.
 #include <pthread.h>
 
 int pthread_key_delete(
-pthread_key_t key,
-);
+pthread_key_t key);
 @end example
 
 @subheading STATUS CODES:
@@ -86,8 +107,22 @@ The key was invalid
 @end table
 
 @subheading DESCRIPTION:
+The pthread_key_delete() function shall delete a thread-specific data key
+previously returned by pthread_key_create(). The thread-specific data
+values associated with key need not be NULL at the time pthread_key_delete()
+is called. It is the responsibility of the application to free any
+application storage or perform any cleanup actions for data structures related
+to the deleted key or associated thread-specific data in any
+threads; this cleanup can be done either before or after
+pthread_key_delete() is called. Any attempt to use key following the call to
+pthread_key_delete() results in undefined behavior.
 
 @subheading NOTES:
+The pthread_key_delete() function shall be callable from within
+destructor functions. No destructor functions shall be invoked by
+pthread_key_delete(). Any destructor function that may have been
+associated with key shall no longer be called upon thread exit.
+
 
 @c
 @c
@@ -114,8 +149,22 @@ The specified key is invalid.
 @end table
 
 @subheading DESCRIPTION:
+The pthread_setspecific() function shall associate a thread-specific value
+with a key obtained via a previous call to pthread_key_create().
+Different threads may bind different values to the same key. These values
+are typically pointers to blocks of dynamically allocated memory that
+have been reserved for use by the calling thread.
+	
+ at subheading NOTES:	
+The effect of calling pthread_setspecific() with a key value not obtained
+from pthread_key_create() or after key has
+been deleted with pthread_key_delete() is undefined.
+
+pthread_setspecific() may be called from a thread-specific data
+destructor function. Calling pthread_setspecific() from a thread-specific
+data destructor routine may result either in lost storage (after at least
+PTHREAD_DESTRUCTOR_ITERATIONS attempts at destruction) or in an infinite loop.
 
- at subheading NOTES:
 
 @c
 @c
@@ -144,6 +193,16 @@ The data associated with the specified key.
 @end table
 
 @subheading DESCRIPTION:
+The pthread_getspecific() function shall return the value currently bound to
+the specified key on behalf of the calling thread.
 
 @subheading NOTES:
+The effect of calling pthread_getspecific() with a key value not obtained from
+pthread_key_create() or after key has
+been deleted with pthread_key_delete() is undefined.
+
+pthread_getspecific() may be called from a thread-specific data destructor
+function. A call to pthread_getspecific() for the thread-specific data key
+being destroyed shall return the value NULL, unless the value is changed
+(after the destructor starts) by a call to pthread_setspecific().