HP-UX Reference (11i v2 04/09) - 3 Library Functions N-Z (vol 7)

p
pthread_key_create(3T) pthread_key_create(3T)
(Pthread Library)
NAME
pthread_key_create(), pthread_key_delete() - create or delete a thread-specific data key
SYNOPSIS
#include <pthread.h>
int pthread_key_create(
pthread_key_t *key,
void (*destructor)(void *)
);
int pthread_key_delete(
pthread_key_t key
);
PARAMETERS
key This is either a pointer to the location where the new key value will to be returned
(create function) or the thread-specific data key to be deleted (delete function).
destructor
Function to be called to destroy a data value associated with key when the thread ter-
minates.
DESCRIPTION
pthread_key_create()
creates a unique thread-specific data key. The key may be used by threads
within the process to maintain thread-specific data. The same key is used by all threads, but each thread
has its own thread-specific value associated with key. For each thread, the value associated with key per-
sists for the life of the thread.
A process may create up to
PTHREAD_KEYS_MAX
thread-specific data keys. When a new thread-specific
data key is created, each thread will initially have the value
NULL associated with the new key. Each
time a thread is created, the new thread will have the value NULL for each thread-specific data key that
has been created in the process. A thread may use pthread_setspecific()
to change the value
associated with a thread-specific data key. Note:
pthread_key_t
is an opaque data type.
When a thread terminates, it may have non-
NULL values associated with some or all of its thread-specific
data keys. Typically, these values will be pointers to dynamically allocated memory. If this memory is
not released when the thread terminates, memory leaks in the process occur. An optional destruc-
tor() function may be provided at key creation time to destroy the thread-specific data of a terminating
thread. When a thread terminates, the thread-specific data values associated with the thread will be
examined. For each key that has a non-NULL thread-specific data value and a destructor function, the
destructor function will be called with the thread-specific data value as its sole argument. The order in
which destructor functions are called is unspecified.
Once all the destructor functions have been called, the thread-specific data values for the terminating
thread are examined again. If there are still non-
NULL values in which the associated keys have destruc-
tor functions, the process of calling destructor functions is repeated. If after
PTHREAD_DESTRUCTOR_ITERATIONS iterations of this loop there are still some non-
NULL values
with associated destructors, the system may stop calling the destructors or continue calling the destruc-
tors until there are no non-
NULL values. Note: This may result in an infinite loop.
If a destructor function is not desired for key, the value
NULL may be passed in the destructor parameter.
The
pthread_key_delete() function deletes a thread-specific data key. The key must have been
previously created by pthread_key_create(). The thread-specific data values associated with key
are not required to be
NULL when this function is called. Using key after it has been deleted results in
undefined behavior.
If a destructor function is associated with key, it will not be invoked by the
pthread_key_delete()
function. Once key has been deleted, any destructor function that was associated with key is not
called when a thread exits. It is the responsibility of the application to free any application storage for
each of the threads using key.
The
pthread_key_delete() function can be called from a destructor function.
Section 3−−792 Hewlett-Packard Company − 1 − HP-UX 11i Version 2: September 2004