pthread_keycreate

Generates a unique per-thread context key value.

Syntax

pthread_keycreate(
                  key,
                  destructor );
 



Argument         Data Type               Access

key              opaque pthread_key_t    write

destructor       procedure pthread_      read
                 destructor_t

C Binding

int
pthread_keycreate (
pthread_key_t *key,
pthread_destructor_t destructor);

Arguments

key

Value of the new per-thread context key.

destructor

Procedure called to destroy a context value associated with the created key when the thread terminates.

Description

Per-thread context allows client software to associate context information with the current thread. (This mechanism can be thought of as a means for a client to add unique fields to the thread control block.)

For example, per-thread context can be used by a language run-time library that needs to associate a language-specific thread-private data structure with an individual thread. The per-thread context routines also provide a portable means of implementing the class of storage called thread-private static, which is needed to support parallel decomposition in the Fortran language.

This routine generates and returns a new key value. The key provides a cell within each thread. Each call to this routine creates a new cell, and each call within a process returns a key value that is unique within an application invocation. Keys must be generated from initialization code that is guaranteed to be called only once within each process. (See the pthread_once description for more information.)

When multiple facilities share access to per-thread context, the facilities must agree on the key value that is associated with the context. The key value must be created once and should be stored in a location known to each facility. (Encapsulate key creation and context value setting within a special facility for that purpose.)

An implementation can choose to predefine some number of keys for favored clients, such as certain compilers, run-time libraries, or the debugger.

When a thread terminates, its per-thread context is automatically destroyed; however, the key value remains. For each per-thread context currently associated with the thread, the destructor routine associated with the key value of that context is called. The order in which per-thread context destructors are called at thread termination is undefined.

Upon key creation, the value NULL is 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.

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 function pointed to is called with the current 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.

If after the destructors have been called for all non-NULL values with associated destructors, there are still some non-NULL values with associated destructores, then the process shall be repeated. If, after at least {PTHREAD_DESTRUCTOR_ITERATIONS} iterations of destructor calls for outstanding non-NULL values, there are still some non-values with associated destructors, an application can stop calling destructors, or the application can continue calling destructors until no non-NULL values with the associated destructors exists, even though this might result in an infinite loop.

Return Values

Return  Error         Description

0                     Successful completion.

-1      [EAGAIN]      An attempt is made to allocate a key when the
                      key name space is exhausted. This is not a
                      temporary condition.

-1      [ENOMEM]      Insufficient memory exists to create the key.

-1      [EINVAL]      Invalid argument.