cma_key_create

Generates a unique per-thread context key value.

Syntax

cma_key_create(
                key,
                attr,
                destructor);
 



Argument         Data Type               Access

key              opaque cma_t_key        write

attr             opaque cma_t_attr       read

destructor       procedure cma_t_        read
                 destructor

C Binding

#include 


void
cma_key_create (
         cma_t_key   *key,
         cma_t_attr   *attr,
         cma_t_destructor   destructor);

Arguments

key

Receives the value of the new per-thread context key.

attr

Handle of the attributes object that defines the characteristics of the per-thread context key being created.

destructor

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

Description

Per-thread context is a mechanism that 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 its own unique fields to the thread control block.)

This routine generates and returns a new key value. Each call to this routine 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. (Refer to the description of cma_once 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 only once, and should be stored in a location known to each facility. (It may be desirable to encapsulate the creation of a key, and the setting and getting of context values for that key, within a special facility created for that purpose.)

When a thread terminates, per-thread context is automatically destroyed. For each per-thread context currently associated with the thread, the destructor routine associated with the key value of that context is called.

Exceptions

cma_e_existence
cma_e_use_error