tis_key_create

Generates a unique thread-specific data key.

Syntax

tis_key_create(
               key,
               destructor );
 



Argument         Data Type               Access

key              opaque pthread_key_t    write

destructor       procedure               read

C Binding

#include 


int
tis_key_create (
   pthread_key_t   *key,
   void   (*destructor)(void *));

Arguments

key

Address of a variable which will receive the key value. This value is used in calls to tis_getspecific and tis_setspecific to get and set the value associated with this key.

destructor

Address of a routine which is called to destroy the context value when a thread terminates with a non-NULL value for the key. Note that this argument is only utilized when threads are present.

Description

This routine generates and returns a new key value. The key reserves a cell. Each call to this routine creates a new cell 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 tis_once description for more information.)

An optional destructor function may be associated with each key. At thread exit, if a key has a non-NULL destructor function 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 in which data destructors are called at thread termination is undefined.

When threads are present, keys and any corresponding data are thread-specific; they enable the context to be maintained on a per- thread basis. For more information concerning the use of tis_key_ create in a threaded environment, refer to the pthread_key_create description.

Return Values

Return        Description

0             Successful completion.

[EAGAIN]      The system lacked the necessary resources to create
              another thread-specific data key, or the system-
              imposed limit on the total number of keys per process
              {PTHREAD_KEYS_MAX} has been exceeded.

[ENOMEM]      Insufficient memory exists to create the key.

[EINVAL]      Invalid argument.

Associated Routines

   tis_getspecific
   tis_key_delete
   tis_setspecific
   tis_once