pthread_key_create()

Create thread-specific data key

Synopsis:

#include <pthread.h>

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

Library:

libc

Description:

The pthread_key_create() function creates a thread-specific data key that's available to all threads in the process and binds an optional destructor function destructor to the key. If the function completes successfully the new key is returned in key. Although the same key may be used by different threads, the values bound to the key using pthread_setspecific() are maintained on a per-thread basis and persist only for the lifetime of the thread.

Upon key creation, the value NULL is bound with the new key in all active threads. Upon thread creation, the value NULL is bound to all defined keys in the new thread.

An optional destructor function may be associated with each key value. At thread exit, if the key has a non-NULL destructor pointer, and the thread has a non-NULL value bound to the key, the destructor function is called with the bound value as its only argument. The order of destructor calls is unspecified if more than one destructor exists for a thread when it exits.

If, after all destructor functions have been called for a thread there are still non-NULL bound values, then the destructor function will be called repeatedly a maximum of PTHREAD_DESTRUCTOR_ITERATIONS times for each non-NULL bound value.

Returns:

EOK

Success.

EAGAIN

Insufficient system resources to create key or PTHREAD_KEYS_MAX has been exceeded.

ENOMEM

Insufficient memory to create key.

Examples:

This example shows how thread-specific data can be used to provide per thread data in a thread safe function.

#include <stdio.h>
#include <stdlib.h>
#include <pthread.h>

pthread_key_t buffer_key;

void buffer_key_destruct( void *value )
{
    free( value );
    pthread_setspecific( buffer_key, NULL );
}

char *lookup( void )
{
    char *string;

    string = (char *)pthread_getspecific( buffer_key );
    if( string == NULL ) {
        string = (char *) malloc( 32 );
        sprintf( string, "This is thread %d\n", pthread_self() );      
        pthread_setspecific( buffer_key, (void *)string );
    }

    return( string );
}

void *function( void *arg )
{
    while( 1 ) {
        puts( lookup() );
    }

    return( 0 );
}

int main( void )
{
    pthread_key_create( &buffer_key,
                        &buffer_key_destruct );
    pthread_create( NULL, NULL, &function, NULL );

    /* Let the threads run for 60 seconds. */
    sleep( 60 );
    
    return EXIT_SUCCESS;
}

Classification:

POSIX 1003.1 (Threads)

Caveats:

The pthread_key_create() function is part of the POSIX 1003.1-1996 draft standard; its specific behavior may vary from system to system.

Before each destructor is called, the thread's value for the corresponding key is set to NULL. Calling:

pthread_setspecific( key, NULL );

in a key destructor isn't required; this lets you use the same destructor for several keys.

See also:

pthread_getspecific(), pthread_setspecific(), pthread_key_delete()