pthreadkeycreate

pthread_key_create is a function in the POSIX threading API that allocates a key for thread-specific data. A key is global to the process; each thread can associate a distinct value with the key using pthread_setspecific, and retrieve it with pthread_getspecific. The value associated with a key is stored per thread, so threads do not share per-thread data via that key.

The function prototype is int pthread_key_create(pthread_key_t *key, void (*destructor)(void *)); On success, it writes the new key into the location pointed to by key and returns 0. If there is insufficient resources to create a new key, or for other implementation-defined limitations, it returns a non-zero error code (commonly EAGAIN or ENOMEM; some implementations may use EINVAL for invalid arguments).

If the destructor parameter is non-NULL, the destructor is invoked for each thread that has a non-NULL value associated with the key when that thread terminates or when the key is deleted with pthread_key_delete. The destructor receives the per-thread value as its argument. The exact order and number of destructor invocations are implementation-defined; destructors may be invoked multiple times if they reinitialize thread-specific data.

Destroying a key with pthread_key_delete also triggers destructor calls for existing non-NULL per-thread values for that key, then frees the key for reuse. Before using a key, the program must declare a pthread_key_t variable and call pthread_key_create, typically at initialization time.

See also: pthread_getspecific, pthread_setspecific, pthread_key_delete, and POSIX threads.