Generates a unique thread-specific data key.

1  –  C Binding

    #include <tis.h>

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

2  –  Arguments

 key

    Address of a variable that receives the key value. This value
    is used in calls to tis_getspecific() and tis_setspecific()  to
    obtain and set the value associated with this key.

 destructor

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

3  –  Description

    This routine generates a unique thread-specific data key. The key
    argument points to an opaque object used to locate data.

    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.)

    Your program can associate an optional destructor function 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 about the use of tis_key_
    create() in a threaded environment, refer to the pthread_key_
    create() description.

    The Threads Library imposes a maximum number of thread-specific
    data keys, equal to the symbolic constant PTHREAD_KEYS_MAX.

4  –  Return Values

    If an error condition occurs, this routine returns an integer
    indicating the type of error. Possible return values are as
    follows:

    Return      Description

    0           Successful completion.
    [EAGAIN]    The system lacked the necessary resources to create
                another thread-specific data key, or the limit on the
                total number of keys per process (PTHREAD_KEYS_MAX)
                has been exceeded.
    [EINVAL]    The value specified by key is invalid.
    [ENOMEM]    Insufficient memory to create the key.

5  –  Associated Routines

       tis_getspecific()
       tis_key_delete()
       tis_setspecific()
       tis_once()