globus_thread_key(3) [debian man page]
Thread-Specific Storage(3) globus common Thread-Specific Storage(3) NAME
Thread-Specific Storage - Functions int globus_thread_key_create (globus_thread_key_t *key, globus_thread_key_destructor_func_t destructor) int globus_thread_key_delete (globus_thread_key_t key) void * globus_thread_getspecific (globus_thread_key_t key) int globus_thread_setspecific (globus_thread_key_t key, void *value) Detailed Description The globus_thread_key_t data type acts as a key to thread-specific storage. For each key created by globus_thread_key_create(), each thread may store and retrieve its own value. Function Documentation int globus_thread_key_create (globus_thread_key_t *key, globus_thread_key_destructor_func_tdestructor) Create a key for thread-specific storage. .PP The globus_thread_key_create() function creates a new key for thread-specific data. The new key will be available for all threads to store a distinct value. If the function pointer @a destructor is non-NULL, then that function will be invoked when a thread exits that has a non-NULL value associated with the key. Parameters: key Pointer to be set to the new key. destructor Pointer to a function to call when a thread exits to free the key's value. Returns: On success, globus_thread_create_key() will create a new key to thread-local storage and return GLOBUS_SUCCESS. If an error occurs, then the value of key is undefined and globus_thread_create_key() returns an implementation-specific non-zero error value. int globus_thread_key_delete (globus_thread_key_tkey) Delete a thread-local storage key. .PP The globus_thread_key_delete() function deletes the key used for a thread-local storage association. The destructor function for this key will no longer be called after this function returns. The behavior of subsequent calls to globus_thread_getspecific() or globus_thread_setspecific() with this key will be undefined. Parameters: key Key to destroy. Returns: On success, globus_thread_key_delete() will delete a thread-local storage key and return GLOBUS_SUCCESS. If an error occurs, then the value of key is undefined and globus_thread_create_key() returns an implementation-specific non-zero error value. void* globus_thread_getspecific (globus_thread_key_tkey) Get a thread-specific data value. .PP The globus_thread_getspecific() function returns the value associated with the thread-specific data key passed as its first parameter. This function returns NULL if the value has not been set by the current thread. The return value is undefined if the key is not valid. Parameters: key Thread-specific data key to look up. Returns: The value passed to a previous call to globus_thread_setspecific() in the current thread for this key. int globus_thread_setspecific (globus_thread_key_tkey, void *value) Set a thread-specific data value. .PP The globus_thread_setspecific() function associates a thread-specific value with a data key. If the key had a previous value set in the current thread, it is replaced, but the destructor function is not called for the old value. Parameters: key Thread-specific data key to store. value A pointer to data to store as the thread-specific data for this thread. Returns: On success, globus_thread_setspecific() stores value in the thread-specific data for the specified key and returns GLOBUS_SUCCESS. If an error occurs, globus_thread_setspecific() returns an implementation-specific non-zero error code and does not modify the key's value for this thread. Author Generated automatically by Doxygen for globus common from the source code. Version 14.7 Tue Nov 27 2012 Thread-Specific Storage(3)
Check Out this Related Man Page
pthread_key_create(3T) pthread_key_create(3T) NAME
pthread_key_create(), pthread_key_delete() - create or delete a thread-specific data key SYNOPSIS
PARAMETERS
key This is either a pointer to the location where the new key value will to be returned (create function) or the thread-spe- cific data key to be deleted (delete function). destructor Function to be called to destroy a data value associated with key when the thread terminates. DESCRIPTION
creates a unique thread-specific data key. The key may be used by threads within the process to maintain thread-specific data. The same key is used by all threads, but each thread has its own thread-specific value associated with key. For each thread, the value associated with key persists for the life of the thread. By default, the system allows a process to create up to number of thread-specific data keys. If the process needs more keys, the environ- ment variable can set the number of keys up to a maximum of 16384. If a value outside the range of and 16384 is specified, or if the envi- ronment variable is not set at all, the default value is considered. When a new thread-specific data key is created, each thread will ini- tially have the value NULL associated with the new key. Each time a thread is created, the new thread will have the value NULL for each thread-specific data key that has been created in the process. A thread may use to change the value associated with a thread-specific data key. Note: is an opaque data type. When a thread terminates, it may have non-NULL values associated with some or all of its thread-specific data keys. Typically, these val- ues will be pointers to dynamically allocated memory. If this memory is not released when the thread terminates, memory leaks in the process occur. An optional function may be provided at key creation time to destroy the thread-specific data of a terminating thread. When a thread terminates, the thread-specific data values associated with the thread will be examined. For each key that has a non-NULL thread-specific data value and a destructor function, the destructor function will be called with the thread-specific data value as its sole argument. The order in which destructor functions are called is unspecified. Once all the destructor functions have been called, the thread-specific data values for the terminating thread are examined again. If there are still non-NULL values in which the associated keys have destructor functions, the process of calling destructor functions is repeated. If after iterations of this loop there are still some non-NULL values with associated destructors, the system may stop calling the destructors or continue calling the destructors until there are no non-NULL values. Note: This may result in an infinite loop. If a destructor function is not desired for key, the value NULL may be passed in the destructor parameter. The function deletes a thread-specific data key. The key must have been previously created by The thread-specific data values associated with key are not required to be NULL when this function is called. Using key after it has been deleted results in undefined behavior. If a destructor function is associated with key, it will not be invoked by the function. Once key has been deleted, any function that was associated with key is not called when a thread exits. It is the responsibility of the application to free any application storage for each of the threads using key. The function can be called from a destructor function. RETURN VALUE
If successful, and return zero. Otherwise, an error number is returned to indicate the error (the variable is not set). ERRORS
If any of the following occur, the function returns the corresponding error number: The value specified by key is invalid. The necessary resources to create another thread-specific data key are not available, or the total number of keys per process has exceeded or an invalid value was specified with the environment variable There is insufficient memory available in which to create key. For each of the following conditions, if the condition is detected, the function returns the corresponding error number: The value specified by key is invalid. AUTHOR
and were derived from the IEEE POSIX P1003.1c standard. SEE ALSO
pthread_getspecific(3T), pthread_setspecific(3T). STANDARDS CONFORMANCE
Pthread Library pthread_key_create(3T)