Thread-specific data.

Thread-specific data. More...

Collaboration diagram for Thread-specific data.:

Functions
int	pthread_key_create (pthread_key_t *key, void(*destructor)(void *))
	Create a thread-specific data key.
int	pthread_setspecific (pthread_key_t key, const void *value)
	Associate a thread-specific value with the specified key.
void *	pthread_getspecific (pthread_key_t key)
	Get the thread-specific value bound to the specified key.
int	pthread_key_delete (pthread_key_t key)
	Delete a thread-specific data key.

---

Detailed Description

Thread-specific data.

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.

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

The services documented here are valid in kernel-space context; when called in user-space, the underlying Linux threading library (LinuxThreads or NPTL) services are used.

---

Function Documentation

void* pthread_getspecific

(

pthread_key_t

key

)

Get the thread-specific value bound to the specified key.

This service returns the value associated, for the calling thread, with the key key.

Parameters:

key	TSD key, obtained with pthread_key_create().

Returns:

the value associated with key;

NULL if the context is invalid.

Valid contexts:

• Xenomai POSIX skin kernel-space thread.

See also:

Specification.

Referenced by rt_task_self(), and rt_task_shadow().

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

Create a thread-specific data key.

This service create a TSD key. The NULL value is associated for all threads with the new key and the new key is returned at the address key. If destructor is not null, it is executed when a thread is terminated as long as the datum associated with the key is not NULL, up to PTHREAD_DESTRUCTOR_ITERATIONS times.

Parameters:

key	address where the new key will be stored on success;
destructor	function to be invoked when a thread terminates and has a non NULL value associated with the new key.

Returns:

0 on success;

an error number if:

• EAGAIN, the total number of keys PTHREAD_KEYS_MAX TSD has been exceeded;
• ENOMEM, insufficient memory exists in the system heap to create a new key, increase CONFIG_XENO_OPT_SYS_HEAPSZ.

See also:

Specification.

int pthread_key_delete

(

pthread_key_t

key

)

Delete a thread-specific data key.

This service deletes the TSD key key. Note that the key destructor function is not called, so, if any thread has a value associated with key that is a pointer to dynamically allocated memory, the application has to manage to free that memory by other means.

Parameters:

key	the TSD key to be destroyed.

Returns:

0 on success;

an error number if:

• EINVAL, key is invalid.

See also:

Specification.

int pthread_setspecific	(	pthread_key_t	key,
		const void *	value
	)

Associate a thread-specific value with the specified key.

This service associates, for the calling thread, the value value to the key key.

Parameters:

key	TSD key, obtained with pthread_key_create();
value	value.

Returns:

0 on success;

an error number if:

• EPERM, the caller context is invalid;
• EINVAL, key is invalid.

Valid contexts:

• Xenomai POSIX skin kernel-space thread.

See also:

Specification.

Referenced by rt_task_shadow().