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.

ABT_eventual_memory eventual_mem = 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]	nbytes	size in bytes of the memory buffer
[out]	neweventual	eventual 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] eventual eventual 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] eventual eventual 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]	eventual	eventual handle
[in]	value	pointer to the memory buffer
[in]	nbytes	number 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]	eventual	handle to the eventual
[out]	value	pointer to the memory buffer of the eventual
[out]	is_ready	user 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]	eventual	eventual handle
[out]	value	memory buffer of the eventual

Returns: Error code

Definition at line 173 of file eventual.c.

Data Structures

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

◆ ABT_EVENTUAL_INITIALIZER

◆ ABT_EVENTUAL_MEMORY_GET_HANDLE

Typedef Documentation

◆ ABT_eventual

Function Documentation

◆ ABT_eventual_create()

◆ ABT_eventual_free()

◆ ABT_eventual_reset()

◆ ABT_eventual_set()

◆ ABT_eventual_test()

◆ ABT_eventual_wait()