Work-Unit Local Storage (TLS)

Functions
int	ABT_key_create (void(*destructor)(void *value), ABT_key *newkey)
	Create an WU-specific data key. More...
int	ABT_key_free (ABT_key *key)
	Free an WU-specific data key. More...
int	ABT_key_set (ABT_key key, void *value)
	Associate a value with the key. More...
int	ABT_key_get (ABT_key key, void **value)
	Get the value associated with the key. More...

Detailed Description

This group is for work-unit specific data, which can be described as work-unit local storage (TLS).

Function Documentation

int ABT_key_create	(	void(*)(void *value)	destructor,
		ABT_key *	newkey
	)

Create an WU-specific data key.

ABT_key_create() creates a new work unit (WU)-specific data key visible to all WUs (ULTs or tasklets) in the process and returns its handle through newkey. Although the same key may be used by different WUs, the values bound to the key by ABT_key_set() are maintained per WU and persist for the life of the calling WU.

Upon key creation, the value NULL shall be associated with the new key in all active WUs. Upon WU creation, the value NULL shall be associated with all defined keys in the new WU.

An optional destructor function, destructor, may be registered with each key. When a WU terminates, if a key has a non-NULL destructor pointer, and the WU has a non-NULL value associated with that key, the value of the key is set to NULL, and then destructor is called with the previously associated value as its sole argument. The order of destructor calls is unspecified if more than one destructor exists for a WU when it exits.

Parameters

[in]	destructor	destructor function called when a WU exits
[out]	newkey	handle to a newly created key

Returns

Error code

Return values

ABT_SUCCESS

on success

Definition at line 46 of file key.c.

int ABT_key_free

(

ABT_key *

key

)

Free an WU-specific data key.

ABT_key_free() deletes the WU-specific data key specified by key and deallocates memory used for the key object. It is the user's responsibility to free memory for values associated with the deleted key. This routine does not call the destructor function registered by ABT_key_create().

Parameters

[in,out]

key

handle to the target key

Returns

Error code

Return values

ABT_SUCCESS

on success

Definition at line 76 of file key.c.

int ABT_key_get	(	ABT_key	key,
		void **	value
	)

Get the value associated with the key.

ABT_key_get() returns the value associated with the target WU-specific data key, key, through value on behalf of the calling WU. Different WUs get different values for the target key via this routine if they have set different values with ABT_key_set(). If a WU has never set a value for the key, this routine returns NULL to value.

Parameters

[in]	key	handle to the target key
[in]	value	value for the key

Returns

Error code

Return values

ABT_SUCCESS

on success

Definition at line 173 of file key.c.

int ABT_key_set	(	ABT_key	key,
		void *	value
	)

Associate a value with the key.

ABT_key_set() associates a value, value, with the target WU-specific data key, key. Different WUs may bind different values to the same key.

Parameters

[in]	key	handle to the target key
[in]	value	value for the key

Returns

Error code

Return values

ABT_SUCCESS

on success

Definition at line 114 of file key.c.