ARGOBOTS  8bef54a19d7b3e50f977f85716578b627bf37d9c
Typedefs | Functions
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 938 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]destructordestructor function called when a work unit is freed
[out]newkeywork-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]keywork-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]keywork-unit-specific data key handle
[out]valuevalue 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]keywork-unit-specific data key handle
[in]valuevalue associated with key
Returns
Error code

Definition at line 162 of file key.c.