Work-Unit-Specific Data

This group is for work-unit-specific data, which can be described as work-unit local storage (which is similar to "thread-local storage" or TLS). More...

Typedefs
typedef struct ABT_key_opaque *	ABT_key
	Work-unit-specific data key handle type. More...

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

Detailed Description

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

Typedef Documentation

ABT_key

typedef struct ABT_key_opaque* ABT_key

Work-unit-specific data key handle type.

A NULL handle of this type is ABT_KEY_NULL.

Definition at line 980 of file abt.h.

Function Documentation

ABT_key_create()

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

Create a new work-unit-specific data key.

ABT_key_create() creates a new work-unit-specific data key visible and returns its handle through newkey. Although the same key may be used by different work units, the values bound to the key set by ABT_key_set() are maintained on a per-work-unit and persist for the life of each work unit.

Upon key creation, the value NULL will be associated with newkey in all existing work units. Upon work-unit creation, the value NULL will be associated with all the defined keys in the new work unit.

An optional destructor function destructor() may be registered to newkey. When a work unit is freed, if a key has a non-NULL destructor and the work unit 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 last associated value as its sole argument value. The destructor is called before the work unit is freed. The order of destructor calls is undefined if more than one destructor exists for a work unit when it is freed.

Note

destructor() is called when a work unit is freed (e.g., ABT_thread_free()), not joined (e.g., ABT_thread_join()).

Unlike other implementations (e.g., pthread_key_create()), destructor() is not called by the associated work-unit, so a program that relies on a caller of destructor() is non-conforming.

destructor() is called even if the associated key has already been freed by ABT_key_free().

The created key must be freed by ABT_key_free() after its use.

Execution context

This routine can be called in any execution context. Argobots must be initialized. This routine does not switch the context of the calling ULT unless any user-defined function that is involved in this routine switch the context of the calling ULT.

Errors

ABT_SUCCESS is returned if this routine succeeds.
ABT_ERR_MEM is returned if memory allocation fails.
ABT_ERR_SYS is returned if an error related to system calls and standard libraries occurs.

Undefined behavior

If Argobots is not initialized, the results are undefined.
If newkey is NULL, the results are undefined.

Parameters

[in]	destructor	destructor function called when a work unit is freed
[out]	newkey	work-unit-specific data key handle

Returns

Error code

Definition at line 66 of file key.c.

ABT_key_free()

int ABT_key_free

(

ABT_key *

key

)

Free a work-unit-specific data key.

ABT_key_free() deallocates the resource used for the work-unit-specific data key key and sets key to ABT_KEY_NULL.

It is the user's responsibility to free memory for values associated with the deleted key.

The user is allowed to delete a key before terminating all work units that have non-NULL values associated with key. The user cannot refer to a value via the deleted key, but the destructor of the deleted key is called when a work unit is freed.

Execution context

This routine can be called in any execution context. Argobots must be initialized. This routine does not switch the context of the calling ULT unless any user-defined function that is involved in this routine switch the context of the calling ULT.

Errors

ABT_SUCCESS is returned if this routine succeeds.
ABT_ERR_INV_KEY is returned if key points to ABT_KEY_NULL.

Undefined behavior

If Argobots is not initialized, the results are undefined.
If key is NULL, the results are undefined.
If key is accessed after calling this routine, the results are undefined.

Parameters

[in,out]

key

work-unit-specific data key handle

Returns

Error code

Definition at line 112 of file key.c.

ABT_key_get()

int ABT_key_get	(	ABT_key	key,
		void **	value
	)

Get a value associated with a work-unit-specific data key in the calling work unit.

ABT_key_get() returns the value in the caller associated with the work-unit-specific data key key in the calling work unit through value. If the caller has never set a value for key, this routine sets value to NULL.

Work-unit-specific values associated with a work-unit-specific data key are read and updated atomically.

Note

This routine will be replaced by ABT_self_get_specific() in the future.

Changes from Argobots 1.x to Argobots 2.0 (planned)

[Argobots 1.x] This routine returns ABT_ERR_UNINITIALIZED if Argobots is not initialized.
[Argobots 2.0] The results of this routine are undefined if Argobots is not initialized.

Rationale

From Argobots 2.0, Argobots routines do not check if Argobots is initialized unless otherwise noted. This omission can reduce the branches that are unnecessary in most cases.

Execution context

This routine can be called in a ULT context or a tasklet context. Argobots must be initialized. This routine does not switch the context of the calling ULT unless any user-defined function that is involved in this routine switch the context of the calling ULT.

Errors

ABT_SUCCESS is returned if this routine succeeds.
ABT_ERR_INV_XSTREAM is returned if the caller is an external thread.
ABT_ERR_INV_KEY is returned if key is ABT_KEY_NULL.
[Argobots 1.x] ABT_ERR_UNINITIALIZED is returned if the Argobots runtime is not initialized.

Undefined behavior

If value is NULL, the results are undefined.
[Argobots 2.0] If Argobots is not initialized, the results are undefined.

Parameters

[in]	key	work-unit-specific data key handle
[out]	value	value associated with key

Returns

Error code

Definition at line 221 of file key.c.

ABT_key_set()

int ABT_key_set	(	ABT_key	key,
		void *	value
	)

Associate a value with a work-unit-specific data key in the calling work unit.

ABT_key_set() associates a value value with the work-unit-specific data key key in the calling work unit. Different work units may bind different values to the same key.

Work-unit-specific values associated with a work-unit-specific data key are read and updated atomically.

Note

This routine will be replaced by ABT_self_set_specific() in the future.

Changes from Argobots 1.x to Argobots 2.0 (planned)

[Argobots 1.x] This routine returns ABT_ERR_UNINITIALIZED if Argobots is not initialized.
[Argobots 2.0] The results of this routine are undefined if Argobots is not initialized.

Rationale

From Argobots 2.0, Argobots routines do not check if Argobots is initialized unless otherwise noted. This omission can reduce the branches that are unnecessary in most cases.

Execution context

This routine can be called in a ULT context or a tasklet context. Argobots must be initialized. This routine does not switch the context of the calling ULT unless any user-defined function that is involved in this routine switch the context of the calling ULT.

Errors

ABT_SUCCESS is returned if this routine succeeds.
ABT_ERR_INV_XSTREAM is returned if the caller is an external thread.
ABT_ERR_INV_KEY is returned if key is ABT_KEY_NULL.
ABT_ERR_MEM is returned if memory allocation fails.
ABT_ERR_SYS is returned if an error related to system calls and standard libraries occurs.
[Argobots 1.x] ABT_ERR_UNINITIALIZED is returned if the Argobots runtime is not initialized.

Undefined behavior

[Argobots 2.0] If Argobots is not initialized, the results are undefined.

Parameters

[in]	key	work-unit-specific data key handle
[in]	value	value associated with key

Returns

Error code

Definition at line 162 of file key.c.