pthread_key_create.txt

来自「Pthread lib库完整说明文档」· 文本 代码 · 共 96 行

           
--------------------------------------------------------------------------------
AIX Version 4.3 Base Operating System and Extensions Technical Reference, Volume
                                       1
--------------------------------------------------------------------------------

pthread_key_create Subroutine

Purpose

Creates a thread-specific data key.

Library

Threads Library (libpthreads.a)

Syntax

#include <pthread.h>

int pthread_key_create ( key, destructor )

pthread_key_t * key;

void (*destructor) (void *);

Description

The pthread_key_create subroutine creates a thread-specific data key. The key is
shared among all threads within the process, but each thread has specific data
associated with the key. The thread-specific data is a void pointer, initially
set to NULL.

The application is responsible for ensuring that this subroutine is called only
once for each requested key. This can be done, for example, by calling the
subroutine before creating other threads, or by using the one-time initialization
facility.

Typically, thread-specific data are pointers to dynamically allocated storage.
When freeing the storage, the value should be set to NULL. It is not recommended
to cast this pointer into scalar data type (int for example), because the casts
may not be portable, and because the value of NULL is implementation dependent.

An optional destructor routine can be specified. It will be called for each
thread when it is terminated and detached, after the call to the cleanup
routines, if the specific value is not NULL. Typically, the destructor routine
will release the storage thread-specific data. It will receive the
thread-specific data as a parameter.

    Note: The pthread.h header file must be the first included file of each
    source file using the threads library. Otherwise, the -D_THREAD_SAFE
    compilation flag should be used, or the cc_r compiler used. In this case, the
    flag is automatically set.

Parameters

key Points to where the key will be stored.

destructor Points to an optional destructor routine, used to cleanup data on
thread termination. If no cleanup is desired, this pointer should be NULL.

Return Values

If successful, the pthread_key_create function stores the newly created key value
at *key and returns zero. Otherwise, an error number is returned to indicate the
error.

Error Codes

The pthread_key_create function will fail if:

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.

The pthread_key_create function will not return an error code of EINTR.

Implementation Specifics

This subroutine is part of the Base Operating System (BOS) Runtime.

Related Information

The pthread_exit subroutine, pthread_key_delete subroutine, pthread_getspecific
subroutne, pthread_once subroutine, pthread.h file.

Thread-Specific Data in AIX Version 4.3 General Programming Concepts: Writing and
Debugging Programs.

Threads Library Quick Reference in AIX Version 4.3 General Programming Concepts:
Writing and Debugging Programs.
--------------------------------------------------------------------------------