From 3562e78743202e43aec8727005182a2558117eca Mon Sep 17 00:00:00 2001 From: marha Date: Sun, 28 Jun 2009 22:07:26 +0000 Subject: Checked in the following released items: xkeyboard-config-1.4.tar.gz ttf-bitstream-vera-1.10.tar.gz font-alias-1.0.1.tar.gz font-sun-misc-1.0.0.tar.gz font-sun-misc-1.0.0.tar.gz font-sony-misc-1.0.0.tar.gz font-schumacher-misc-1.0.0.tar.gz font-mutt-misc-1.0.0.tar.gz font-misc-misc-1.0.0.tar.gz font-misc-meltho-1.0.0.tar.gz font-micro-misc-1.0.0.tar.gz font-jis-misc-1.0.0.tar.gz font-isas-misc-1.0.0.tar.gz font-dec-misc-1.0.0.tar.gz font-daewoo-misc-1.0.0.tar.gz font-cursor-misc-1.0.0.tar.gz font-arabic-misc-1.0.0.tar.gz font-winitzki-cyrillic-1.0.0.tar.gz font-misc-cyrillic-1.0.0.tar.gz font-cronyx-cyrillic-1.0.0.tar.gz font-screen-cyrillic-1.0.1.tar.gz font-xfree86-type1-1.0.1.tar.gz font-adobe-utopia-type1-1.0.1.tar.gz font-ibm-type1-1.0.0.tar.gz font-bitstream-type1-1.0.0.tar.gz font-bitstream-speedo-1.0.0.tar.gz font-bh-ttf-1.0.0.tar.gz font-bh-type1-1.0.0.tar.gz font-bitstream-100dpi-1.0.0.tar.gz font-bh-lucidatypewriter-100dpi-1.0.0.tar.gz font-bh-100dpi-1.0.0.tar.gz font-adobe-utopia-100dpi-1.0.1.tar.gz font-adobe-100dpi-1.0.0.tar.gz font-util-1.0.1.tar.gz font-bitstream-75dpi-1.0.0.tar.gz font-bh-lucidatypewriter-75dpi-1.0.0.tar.gz font-adobe-utopia-75dpi-1.0.1.tar.gz font-bh-75dpi-1.0.0.tar.gz bdftopcf-1.0.1.tar.gz font-adobe-75dpi-1.0.0.tar.gz mkfontscale-1.0.6.tar.gz openssl-0.9.8k.tar.gz bigreqsproto-1.0.2.tar.gz xtrans-1.2.2.tar.gz resourceproto-1.0.2.tar.gz inputproto-1.4.4.tar.gz compositeproto-0.4.tar.gz damageproto-1.1.0.tar.gz zlib-1.2.3.tar.gz xkbcomp-1.0.5.tar.gz freetype-2.3.9.tar.gz pthreads-w32-2-8-0-release.tar.gz pixman-0.12.0.tar.gz kbproto-1.0.3.tar.gz evieext-1.0.2.tar.gz fixesproto-4.0.tar.gz recordproto-1.13.2.tar.gz randrproto-1.2.2.tar.gz scrnsaverproto-1.1.0.tar.gz renderproto-0.9.3.tar.gz xcmiscproto-1.1.2.tar.gz fontsproto-2.0.2.tar.gz xextproto-7.0.3.tar.gz xproto-7.0.14.tar.gz libXdmcp-1.0.2.tar.gz libxkbfile-1.0.5.tar.gz libfontenc-1.0.4.tar.gz libXfont-1.3.4.tar.gz libX11-1.1.5.tar.gz libXau-1.0.4.tar.gz libxcb-1.1.tar.gz xorg-server-1.5.3.tar.gz --- pthreads/manual/pthread_key_create.html | 211 ++++++++++++++++++++++++++++++++ 1 file changed, 211 insertions(+) create mode 100644 pthreads/manual/pthread_key_create.html (limited to 'pthreads/manual/pthread_key_create.html') diff --git a/pthreads/manual/pthread_key_create.html b/pthreads/manual/pthread_key_create.html new file mode 100644 index 000000000..5ecca6995 --- /dev/null +++ b/pthreads/manual/pthread_key_create.html @@ -0,0 +1,211 @@ + + + + + PTHREAD_SPECIFIC(3) manual page + + + + + + + +

POSIX Threads for Windows – REFERENCE - Pthreads-w32

+

Reference Index

+

Table of Contents

+

Name

+

pthread_key_create, pthread_key_delete, pthread_setspecific, +pthread_getspecific - management of thread-specific data +

+

Synopsis

+

#include <pthread.h> +

+

int pthread_key_create(pthread_key_t *key, void +(*destr_function) (void *)); +

+

int pthread_key_delete(pthread_key_t key); +

+

int pthread_setspecific(pthread_key_t key, const +void *pointer); +

+

void * pthread_getspecific(pthread_key_t key); +

+

Description

+

Programs often need global or static variables that have different +values in different threads. Since threads share one memory space, +this cannot be achieved with regular variables. Thread-specific data +is the POSIX threads answer to this need. +

+

Each thread possesses a private memory block, the thread-specific +data area, or TSD area for short. This area is indexed by TSD keys. +The TSD area associates values of type void * to TSD keys. TSD +keys are common to all threads, but the value associated with a given +TSD key can be different in each thread. +

+

For concreteness, the TSD areas can be viewed as arrays of void +* pointers, TSD keys as integer indices into these arrays, and +the value of a TSD key as the value of the corresponding array +element in the calling thread. +

+

When a thread is created, its TSD area initially associates NULL +with all keys. +

+

pthread_key_create allocates a new TSD key. The key is +stored in the location pointed to by key. There is a limit of +PTHREAD_KEYS_MAX on the number of keys allocated at a given +time. The value initially associated with the returned key is NULL +in all currently executing threads. +

+

The destr_function argument, if not NULL, specifies +a destructor function associated with the key. When a thread +terminates via pthread_exit or by cancellation, destr_function +is called with arguments the value associated with the key in that +thread. The destr_function is not called if that value is NULL +or the key has been deleted. The order in which destructor +functions are called at thread termination time is unspecified. +

+

Before the destructor function is called, the NULL value is +associated with the key in the current thread. A destructor function +might, however, re-associate non- NULL values to that key or +some other key. To deal with this, if after all the destructors have +been called for all non- NULL values, there are still some +non- NULL values with associated destructors, then the process +is repeated.

+

pthread_key_delete deallocates a TSD key. It does not check +whether non- NULL values are associated with that key in the +currently executing threads, nor call the destructor function +associated with the key. +

+

pthread_setspecific changes the value associated with key +in the calling thread, storing the given pointer instead. +

+

pthread_getspecific returns the value currently associated +with key in the calling thread. +

+

The routines pthread_setspecific, pthread_getspecific, +and pthread_key_delete can be called from destr_function +targeting any valid key including the key on which destr_function +is currently operating. If pthread_getspecific is called on +the key whose thread specific data is being destroyed, the value NULL +is returned, unless pthread_setspecific was called previously +on that key from within destr_function to set the value to +non-NULL. For some implementations the effect of calling +pthread_setspecific from within destr_function can be +either memory leakage or infinite loops if destr_function has +already been called at least PTHREAD_DESTRUCTOR_ITERATIONS +times.

+

Pthreads-w32 stops running key +destr_function routines after PTHREAD_DESTRUCTOR_ITERATIONS +iterations, even if some non- NULL values with associated +descriptors remain. If memory is allocated and associated with a key +from within destr_function, that memory may not be reclaimed +because that key's destr_function, may not run again.

+

Return Value

+

pthread_key_create, pthread_key_delete, and +pthread_setspecific return 0 on success and a non-zero error +code on failure. If successful, pthread_key_create stores the +newly allocated key in the location pointed to by its key +argument. +

+

pthread_getspecific returns the value associated with key +on success, and NULL on error. +

+

Errors

+

pthread_key_create returns the following error code on +error: +

+
+
+
EAGAIN +
+
+
+PTHREAD_KEYS_MAX keys are already allocated +
+
+
+
ENOMEM +
+
+
+Insufficient memory to allocate the key. +
+

pthread_key_delete and pthread_setspecific return +the following error code on error: +

+
+
+
EINVAL +
+ key is not a valid, allocated TSD key +
+
+

+pthread_getspecific returns NULL if key is not a +valid, allocated TSD key. +

+

Author

+

Xavier Leroy <Xavier.Leroy@inria.fr> +

+

Modified by Ross Johnson for use with Pthreads-w32.

+

See Also

+

pthread_create(3) , +pthread_exit(3) , +pthread_testcancel(3) . +

+

Example

+

The following code fragment allocates a thread-specific array of +100 characters, with automatic reclamation at thread exit: +

+


+
+
/* Key for the thread-specific buffer */
+static pthread_key_t buffer_key;
+/* Once-only initialisation of the key */
+static pthread_once_t buffer_key_once = PTHREAD_ONCE_INIT;
+/* Allocate the thread-specific buffer */
+void buffer_alloc(void)
+{
+  pthread_once(&buffer_key_once, buffer_key_alloc);
+  pthread_setspecific(buffer_key, malloc(100));
+}
+/* Return the thread-specific buffer */
+char * get_buffer(void)
+{
+  return (char *) pthread_getspecific(buffer_key);
+}
+/* Allocate the key */
+static void buffer_key_alloc()
+{
+  pthread_key_create(&buffer_key, buffer_destroy);
+}
+/* Free the thread-specific buffer */
+static void buffer_destroy(void * buf)
+{
+  free(buf);
+}
+
+
+Table of Contents
+ + + \ No newline at end of file -- cgit v1.2.3