linuxthreads/man/pthread_key_create.man

   1 .TH PTHREAD_SPECIFIC 3 LinuxThreads
   2
   3 .SH NAME
   4 pthread_key_create, pthread_key_delete, pthread_setspecific, pthread_getspecific \- management of thread-specific data
   5
   6 .SH SYNOPSIS
   7 #include <pthread.h>
   8
   9 int pthread_key_create(pthread_key_t *key, void (*destr_function) (void *));
  10
  11 int pthread_key_delete(pthread_key_t key);
  12
  13 int pthread_setspecific(pthread_key_t key, const void *pointer);
  14
  15 void * pthread_getspecific(pthread_key_t key);
  16
  17 .SH DESCRIPTION
  18
  19 Programs often need global or static variables that have different
  20 values in different threads. Since threads share one memory space,
  21 this cannot be achieved with regular variables. Thread-specific data
  22 is the POSIX threads answer to this need.
  23
  24 Each thread possesses a private memory block, the thread-specific data
  25 area, or TSD area for short. This area is indexed by TSD keys. The TSD
  26 area associates values of type !void *! to TSD keys. TSD keys are
  27 common to all threads, but the value associated with a given TSD key
  28 can be different in each thread.
  29
  30 For concreteness, the TSD areas can be viewed as arrays of !void *!
  31 pointers, TSD keys as integer indices into these arrays, and the value
  32 of a TSD key as the value of the corresponding array element in the
  33 calling thread.
  34
  35 When a thread is created, its TSD area initially associates !NULL!
  36 with all keys.
  37
  38 !pthread_key_create! allocates a new TSD key. The key is stored in the
  39 location pointed to by |key|. There is a limit of !PTHREAD_KEYS_MAX!
  40 on the number of keys allocated at a given time. The value initially
  41 associated with the returned key is !NULL! in all currently executing
  42 threads.
  43
  44 The |destr_function| argument, if not !NULL!, specifies a destructor
  45 function associated with the key. When a thread terminates via
  46 !pthread_exit! or by cancellation, |destr_function| is called with
  47 arguments the value associated with the key in that thread. The
  48 |destr_function| is not called if that value is !NULL!. The order in
  49 which destructor functions are called at thread termination time is
  50 unspecified.
  51
  52 Before the destructor function is called, the !NULL! value is
  53 associated with the key in the current thread.  A destructor function
  54 might, however, re-associate non-!NULL! values to that key or some
  55 other key.  To deal with this, if after all the destructors have been
  56 called for all non-!NULL! values, there are still some non-!NULL!
  57 values with associated destructors, then the process is repeated.  The
  58 LinuxThreads implementation stops the process after
  59 !PTHREAD_DESTRUCTOR_ITERATIONS! iterations, even if some non-!NULL!
  60 values with associated descriptors remain.  Other implementations may
  61 loop indefinitely.
  62
  63 !pthread_key_delete! deallocates a TSD key. It does not check whether
  64 non-!NULL! values are associated with that key in the currently
  65 executing threads, nor call the destructor function associated with
  66 the key.
  67
  68 !pthread_setspecific! changes the value associated with |key| in the
  69 calling thread, storing the given |pointer| instead.
  70
  71 !pthread_getspecific! returns the value currently associated with
  72 |key| in the calling thread.
  73
  74 .SH "RETURN VALUE"
  75
  76 !pthread_key_create!, !pthread_key_delete!, and !pthread_setspecific!
  77 return 0 on success and a non-zero error code on failure. If
  78 successful, !pthread_key_create! stores the newly allocated key in the
  79 location pointed to by its |key| argument.
  80
  81 !pthread_getspecific! returns the value associated with |key| on
  82 success, and !NULL! on error.
  83
  84 .SH ERRORS
  85 !pthread_key_create! returns the following error code on error:
  86 .RS
  87 .TP
  88 !EAGAIN!
  89 !PTHREAD_KEYS_MAX! keys are already allocated
  90 .RE
  91
  92 !pthread_key_delete! and !pthread_setspecific! return the following
  93 error code on error:
  94 .RS
  95 .TP
  96 !EINVAL!
  97 |key| is not a valid, allocated TSD key
  98 .RE
  99
 100 !pthread_getspecific! returns !NULL! if |key| is not a valid,
 101 allocated TSD key.
 102
 103 .SH AUTHOR
 104 Xavier Leroy <Xavier.Leroy@inria.fr>
 105
 106 .SH "SEE ALSO"
 107 pthread_create(3), pthread_exit(3), pthread_testcancel(3).
 108
 109 .SH EXAMPLE
 110
 111 The following code fragment allocates a thread-specific array of 100
 112 characters, with automatic reclaimation at thread exit:
 113
 114 .RS
 115 .ft 3
 116 .nf
 117 .sp
 118 /* Key for the thread-specific buffer */
 119 static pthread_key_t buffer_key;
 120
 121 /* Once-only initialisation of the key */
 122 static pthread_once_t buffer_key_once = PTHREAD_ONCE_INIT;
 123
 124 /* Allocate the thread-specific buffer */
 125 void buffer_alloc(void)
 126 {
 127   pthread_once(&buffer_key_once, buffer_key_alloc);
 128   pthread_setspecific(buffer_key, malloc(100));
 129 }
 130
 131 /* Return the thread-specific buffer */
 132 char * get_buffer(void)
 133 {
 134   return (char *) pthread_getspecific(buffer_key);
 135 }
 136
 137 /* Allocate the key */
 138 static void buffer_key_alloc()
 139 {
 140   pthread_key_create(&buffer_key, buffer_destroy);
 141 }
 142
 143 /* Free the thread-specific buffer */
 144 static void buffer_destroy(void * buf)
 145 {
 146   free(buf);
 147 }
 148 .ft
 149 .LP
 150 .RE
 151 .fi