ARGOBOTS  dce6e727ffc4ca5b3ffc04cb9517c6689be51ec5
Data Structures | Macros | Typedefs | Functions
Eventual

This group is for Eventual. More...

Data Structures

struct  ABT_eventual_memory
 A struct that can be converted to ABT_eventual. More...
 

Macros

#define ABT_EVENTUAL_INITIALIZER   { { 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0 } }
 Initialize ABT_eventual_memory. More...
 
#define ABT_EVENTUAL_MEMORY_GET_HANDLE(p_eventual_memory)   ((ABT_eventual)p_eventual_memory)
 Obtain ABT_eventual from ABT_eventual_memory. More...
 

Typedefs

typedef struct ABT_eventual_opaque * ABT_eventual
 Eventual handle type. More...
 

Functions

int ABT_eventual_create (int nbytes, ABT_eventual *neweventual)
 Create a new eventual. More...
 
int ABT_eventual_free (ABT_eventual *eventual)
 Free an eventual. More...
 
int ABT_eventual_wait (ABT_eventual eventual, void **value)
 Wait on an eventual. More...
 
int ABT_eventual_test (ABT_eventual eventual, void **value, ABT_bool *is_ready)
 Check if an eventual is ready. More...
 
int ABT_eventual_set (ABT_eventual eventual, void *value, int nbytes)
 Signal an eventual. More...
 
int ABT_eventual_reset (ABT_eventual eventual)
 Reset a readiness of an eventual. More...
 

Detailed Description

This group is for Eventual.

Macro Definition Documentation

◆ ABT_EVENTUAL_INITIALIZER

#define ABT_EVENTUAL_INITIALIZER   { { 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0 } }

Initialize ABT_eventual_memory.

ABT_EVENTUAL_INITIALIZER statically initializes ABT_eventual_memory.

The following example shows how to use ABT_EVENTUAL_INITIALIZER.

void thread(void *)
{
ABT_eventual eventual = ABT_EVENTUAL_MEMORY_GET_HANDLE(&eventual_mem);
if (...) {
ABT_eventual_wait(eventual);
} else {
[...];
ABT_eventual_set(eventual, NULL, 0);
}
}

ABT_eventual_memory that is in use may not be initialized again.

Definition at line 1311 of file abt.h.

◆ ABT_EVENTUAL_MEMORY_GET_HANDLE

#define ABT_EVENTUAL_MEMORY_GET_HANDLE (   p_eventual_memory)    ((ABT_eventual)p_eventual_memory)

Obtain ABT_eventual from ABT_eventual_memory.

ABT_EVENTUAL_MEMORY_GET_HANDLE() takes the pointer p_eventual_memory, which points to ABT_eventual_memory, and returns ABT_eventual that internally uses p_eventual_memory to store the data. If the memory pointed to by p_eventual_memory is not properly initialized, it returns a corrupted eventual.

ABT_eventual obtained by ABT_EVENTUAL_MEMORY_GET_HANDLE() may not be freed by ABT_eventual_free(). The lifetime of ABT_eventual obtained by ABT_EVENTUAL_MEMORY_GET_HANDLE() is the same as that of ABT_eventual_memory.

Definition at line 1329 of file abt.h.

Typedef Documentation

◆ ABT_eventual

typedef struct ABT_eventual_opaque* ABT_eventual

Eventual handle type.

A NULL handle of this type is ABT_EVENTUAL_NULL.

Definition at line 1015 of file abt.h.

Function Documentation

◆ ABT_eventual_create()

int ABT_eventual_create ( int  nbytes,
ABT_eventual neweventual 
)

Create a new eventual.

ABT_eventual_create() creates a new eventual and returns its handle through neweventual. neweventual is set to unready. If nbytes is greater than zero, this routine allocates a memory buffer of nbytes bytes for neweventual. This memory buffer can be set by ABT_eventual_set() and read by ABT_eventual_wait() or ABT_eventual_test(). If nbytes is zero, the user cannot pass data from a setter to waiters through neweventual.

neweventual must be freed by ABT_eventual_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_INV_ARG is returned if nbytes is negative.
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 neweventual is NULL, the results are undefined.
Parameters
[in]nbytessize in bytes of the memory buffer
[out]neweventualeventual handle
Returns
Error code

Definition at line 42 of file eventual.c.

◆ ABT_eventual_free()

int ABT_eventual_free ( ABT_eventual eventual)

Free an eventual.

ABT_eventual_free() deallocates the resource used for the eventual eventual and sets eventual to ABT_EVENTUAL_NULL.

Note
This routine frees eventual regardless of its readiness.
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_EVENTUAL is returned if eventual points to ABT_EVENTUAL_NULL.
Undefined behavior
If Argobots is not initialized, the results are undefined.
If eventual is NULL, the results are undefined.
If there is a waiter blocked on eventual, the results are undefined.
If eventual is accessed after calling this routine, the results are undefined.
Parameters
[in,out]eventualeventual handle
Returns
Error code

Definition at line 102 of file eventual.c.

◆ ABT_eventual_reset()

int ABT_eventual_reset ( ABT_eventual  eventual)

Reset a readiness of an eventual.

ABT_eventual_reset() makes the eventual eventual unready.

Note
This routine makes eventual unready irrespective of its readiness.

The readiness of an eventual is managed atomically.

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_EVENTUAL is returned if eventual is ABT_EVENTUAL_NULL.
Undefined behavior
If Argobots is not initialized, the results are undefined.
If there is a waiter blocked on eventual, the results are undefined.
Parameters
[in]eventualeventual handle
Returns
Error code

Definition at line 379 of file eventual.c.

◆ ABT_eventual_set()

int ABT_eventual_set ( ABT_eventual  eventual,
void *  value,
int  nbytes 
)

Signal an eventual.

ABT_eventual_set() makes the eventual eventual ready and resumes all waiters that are blocked on eventual. If nbytes is greater than zero, this routine copies nbytes bytes of the memory buffer pointed to by value to the memory buffer of eventual before making eventual ready.

Note
A ready eventual can be set to unready by ABT_eventual_reset().

The readiness of an eventual is managed atomically.

Changes from Argobots 1.0 to Argobots 1.1
[Argobots 1.0] This routine updates the memory buffer of eventual and returns ABT_SUCCESS if eventual is ready.
[Argobots 1.1] This routine returns ABT_ERR_EVENTUAL if eventual is ready.
Rationale
An update of the memory buffer when eventual is ready breaks the semantics of eventual. Such an update should be prohibited.
Changes from Argobots 1.x to Argobots 2.0 (planned)
[Argobots 1.x] ABT_ERR_INV_EVENTUAL is returned if nbytes is greater than the size of the memory buffer of eventual.
[Argobots 2.0] ABT_ERR_INV_ARG is returned if nbytes is greater than the size of the memory buffer of eventual.
Rationale
Argobots 2.0 changes the error code for consistent behavior with other Argobots routines.
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_ARG is returned if nbytes is negative.
ABT_ERR_INV_EVENTUAL is returned if eventual is ABT_EVENTUAL_NULL.
ABT_ERR_EVENTUAL is returned if eventual is ready.
[Argobots 1.x] ABT_ERR_INV_EVENTUAL is returned if nbytes is larger than the size of the memory buffer of eventual.
[Argobots 2.0] ABT_ERR_INV_ARG is returned if nbytes is larger than the size of the memory buffer of eventual.
Undefined behavior
If Argobots is not initialized, the results are undefined.
If nbytes is greater than zero and value is NULL, the results are undefined.
Parameters
[in]eventualeventual handle
[in]valuepointer to the memory buffer
[in]nbytesnumber of bytes to be copied
Returns
Error code

Definition at line 317 of file eventual.c.

◆ ABT_eventual_test()

int ABT_eventual_test ( ABT_eventual  eventual,
void **  value,
ABT_bool is_ready 
)

Check if an eventual is ready.

ABT_eventual_test() checks if the eventual eventual is ready and returns the result through is_ready. If eventual is not ready, this routine leaves value unchanged and sets is_ready to ABT_FALSE. If eventual is ready, is_ready is set to ABT_TRUE and, if value is not NULL, value is set to the memory buffer of eventual. This routine returns ABT_SUCCESS even if eventual is not ready.

The memory buffer pointed to by value is deallocated when eventual is freed by ABT_eventual_free(). The memory buffer is properly aligned for storage of any type of object that has the given size. If the data written by ABT_eventual_set() is smaller than the size of the memory buffer of eventual, the contents of the memory buffer that was not written by ABT_eventual_set() are undefined. The contents of the memory buffer get undefined if either ABT_eventual_set() or ABT_eventual_reset() is called for eventual. The memory buffer is read-only, so rewriting the contents of the obtained memory buffer causes undefined behavior.

The readiness of an eventual is managed atomically.

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_EVENTUAL is returned if eventual is ABT_EVENTUAL_NULL.
Undefined behavior
If Argobots is not initialized, the results are undefined.
If is_ready is NULL, the results are undefined.
If the memory buffer pointed to by value is accessed after freeing eventual, the results are undefined.
If the memory buffer pointed to by value is modified, the results are undefined.
Parameters
[in]eventualhandle to the eventual
[out]valuepointer to the memory buffer of the eventual
[out]is_readyuser flag
Returns
Error code

Definition at line 248 of file eventual.c.

◆ ABT_eventual_wait()

int ABT_eventual_wait ( ABT_eventual  eventual,
void **  value 
)

Wait on an eventual.

The caller of ABT_eventual_wait() waits on the eventual eventual. If eventual is ready, this routine returns immediately. If eventual is not ready, the caller suspends and will be resumed once eventual gets ready.

If value is not NULL, value is set to the memory buffer of eventual. If value is not NULL but the size of the memory buffer of eventual (i.e., nbytes passed to ABT_eventual_create()) is zero, value is set to NULL.

The memory buffer pointed to by value is deallocated when eventual is freed by ABT_eventual_free(). The memory buffer is properly aligned for storage of any type of object that has the given size. If the data written by ABT_eventual_set() is smaller than the size of the memory buffer of eventual, the contents of the memory buffer that was not written by ABT_eventual_set() are undefined. The contents of the memory buffer get undefined if either ABT_eventual_set() or ABT_eventual_reset() is called for eventual. The memory buffer is read-only, so rewriting the contents of the obtained memory buffer causes undefined behavior.

The readiness of an eventual is managed atomically.

Changes from Argobots 1.x to Argobots 2.0 (planned)
[Argobots 1.x] If a tasklet calls this routine, ABT_ERR_EVENTUAL is returned.
[Argobots 2.0] A tasklet may call this routine.
Rationale
Argobots 2.0 integrates a ULT and a tasklet into a single thread concept to make the API more general.
Execution context
[Argobots 1.x] This routine can be called in a ULT context or an external thread context. Argobots must be initialized. This routine may switch the context of the calling ULT if eventual is not ready. Otherwise, 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.
[Argobots 2.0] This routine can be called in any execution context. Argobots must be initialized. This routine may switch the context of the calling ULT if eventual is not ready. Otherwise, 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_EVENTUAL is returned if eventual is ABT_EVENTUAL_NULL.
[Argobots 1.x] ABT_ERR_EVENTUAL is returned if the caller is a tasklet.
Undefined behavior
If Argobots is not initialized, the results are undefined.
If the memory buffer pointed to by value is accessed after freeing eventual, the results are undefined.
If the memory buffer pointed to by value is modified, the results are undefined.
Parameters
[in]eventualeventual handle
[out]valuememory buffer of the eventual
Returns
Error code

Definition at line 173 of file eventual.c.

ABT_EVENTUAL_MEMORY_GET_HANDLE
#define ABT_EVENTUAL_MEMORY_GET_HANDLE(p_eventual_memory)
Obtain ABT_eventual from ABT_eventual_memory.
Definition: abt.h:1329
ABT_eventual_memory
A struct that can be converted to ABT_eventual.
Definition: abt.h:1283
ABT_eventual
struct ABT_eventual_opaque * ABT_eventual
Eventual handle type.
Definition: abt.h:1015
ABT_eventual_wait
int ABT_eventual_wait(ABT_eventual eventual, void **value) ABT_API_PUBLIC
Wait on an eventual.
Definition: eventual.c:173
ABT_EVENTUAL_INITIALIZER
#define ABT_EVENTUAL_INITIALIZER
Initialize ABT_eventual_memory.
Definition: abt.h:1311
ABT_eventual_set
int ABT_eventual_set(ABT_eventual eventual, void *value, int nbytes) ABT_API_PUBLIC
Signal an eventual.
Definition: eventual.c:317