This group is for Future. More...

Typedefs
typedef struct ABT_future_opaque *	ABT_future
	Future handle type. More...

Functions
int	ABT_future_create (uint32_t num_compartments, void(cb_func)(void arg), ABT_future newfuture)
	Create a new future. More...

int	ABT_future_free (ABT_future *future)
	Free a future. More...

int	ABT_future_wait (ABT_future future)
	Wait on a future. More...

int	ABT_future_test (ABT_future future, ABT_bool *is_ready)
	Check if a future is ready. More...

int	ABT_future_set (ABT_future future, void *value)
	Signal a future. More...

int	ABT_future_reset (ABT_future future)
	Reset readiness of a future. More...

Detailed Description

This group is for Future.

Typedef Documentation

◆ ABT_future

typedef struct ABT_future_opaque* ABT_future

Future handle type.

A NULL handle of this type is ABT_FUTURE_NULL.

Definition at line 1022 of file abt.h.

Function Documentation

◆ ABT_future_create()

int ABT_future_create	(	uint32_t	num_compartments,
		void()(void *arg)	cb_func,
		ABT_future *	newfuture
	)

Create a new future.

ABT_future_create() creates a new future and returns its handle through newfuture. newfuture is unready and has num_compartments compartments. newfuture gets ready if ABT_future_set() for newfuture succeeds num_compartments times.

Note: Calling ABT_future_set() for a future that has no compartment is erroneous. ABT_future_wait() and ABT_future_test() succeed without ABT_future_set() for a future that has no compartment.
cb_func() is never called if num_compartments is zero.

If cb_func is not NULL, the callback function cb_func() is registered to future. cb_func() will be called before all the compartments are set by ABT_future_set(). The caller of cb_func() is undefined, so a program that relies on the caller of cb_func() is non-conforming. The state of the future that invokes cb_func() is undefined in cb_func(). The argument arg of cb_func() is a properly aligned array each of which element stores value passed to ABT_future_set(). The contents of arg are read-only and may not be accessed after cb_func() finishes.

newfuture must be freed by ABT_future_free() after its use.

Changes from Argobots 1.0 to Argobots 1.1

[Argobots 1.0] The order of elements of arg passed to cb_func() is the same order as the ABT_future_set() calls are terminated.
[Argobots 1.1] The order of elements of arg passed to cb_func() is undefined.

Rationale: This specification in Argobots 1.0 is not reasonable because the exact timing of termination of ABT_future_set() is not observable if ABT_future_set() is called concurrently.

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 newfuture is NULL, the results are undefined.
If the contents of the argument arg passed to cb_func() are accessed after cb_func() finishes, the results are undefined.
If a future that triggers cb_func() is accessed in cb_func() itself, the results are undefined.
If the contents of the argument arg passed to cb_func() are modified, the results are undefined.

Parameters

[in]	num_compartments	number of compartments of the future
[in]	cb_func	callback function to be called when the future is ready
[out]	newfuture	future handle

Returns: Error code

Definition at line 61 of file futures.c.

◆ ABT_future_free()

int ABT_future_free ( ABT_future * future )

Free a future.

ABT_future_free() deallocates the resource used for the future future and sets future to ABT_FUTURE_NULL.

Note: This routine frees future 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_FUTURE is returned if future points to ABT_FUTURE_NULL.

Undefined behavior: If Argobots is not initialized, the results are undefined.
If future is NULL, the results are undefined.
If there is a waiter blocked on future, the results are undefined.
If future is accessed after calling this routine, the results are undefined.

Parameters

[in,out] future future handle

Returns: Error code

Definition at line 119 of file futures.c.

◆ ABT_future_reset()

int ABT_future_reset ( ABT_future future )

Reset readiness of a future.

ABT_future_reset() resets the readiness of the future future. A future reset by this routine will get ready if ABT_future_set() succeeds as many times as the number of its compartments.

Note: This routine makes future unready irrespective of its readiness.

The readiness of a future is managed atomically.

Note: This routine has no effect if the number of compartments of future is zero.

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_FUTURE is returned if future is ABT_FUTURE_NULL.

Undefined behavior: If Argobots is not initialized, the results are undefined.
If there is a waiter blocked on future, the results are undefined.

Parameters

[in] future future handle

Returns: Error code

Definition at line 337 of file futures.c.

◆ ABT_future_set()

int ABT_future_set	(	ABT_future	future,
		void *	value
	)

Signal a future.

ABT_future_set() sets a value value to one of the unset compartments of the future future. If all the compartments of future are set, this routine makes future ready and wakes up all waiters that are blocked on future. If the callback function is set to future, the callback function is triggered before future is set to ready.

The readiness of a future 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_FUTURE is returned if future is ABT_FUTURE_NULL.
ABT_ERR_FUTURE is returned if future is ready.
ABT_ERR_FUTURE is returned if the number of compartments of future is zero.

Undefined behavior: If Argobots is not initialized, the results are undefined.

Parameters

[in]	future	future handle
[in]	value	value set to one of the compartments of `future`

Returns: Error code

Definition at line 270 of file futures.c.

◆ ABT_future_test()

int ABT_future_test	(	ABT_future	future,
		ABT_bool *	is_ready
	)

Check if a future is ready.

ABT_future_test() checks if the future future is ready and returns the result through is_ready. If future is ready, this routine sets is_ready to ABT_TRUE. Otherwise, is_ready is set to ABT_FALSE. This routine returns ABT_SUCCESS even if future is not ready.

The readiness of a future 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_FUTURE is returned if future is ABT_FUTURE_NULL.

Undefined behavior: If Argobots is not initialized, the results are undefined.
If is_ready is NULL, the results are undefined.

Parameters

[in]	future	handle to the future
[out]	is_ready	`ABT_TRUE` if future is ready; otherwise, `ABT_FALSE`

Returns: Error code

Definition at line 229 of file futures.c.

◆ ABT_future_wait()

int ABT_future_wait ( ABT_future future )

Wait on a future.

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

The readiness of a future is managed atomically.

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

[Argobots 1.x] If a tasklet calls this routine, ABT_ERR_FUTURE 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 future 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 future 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_FUTURE is returned if future is ABT_FUTURE_NULL.
[Argobots 1.x] ABT_ERR_FUTURE is returned if the caller is a tasklet.

Undefined behavior: If Argobots is not initialized, the results are undefined.

Parameters

[in] future future handle

Returns: Error code

Definition at line 172 of file futures.c.

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ ABT_future

Function Documentation

◆ ABT_future_create()

◆ ABT_future_free()

◆ ABT_future_reset()

◆ ABT_future_set()

◆ ABT_future_test()

◆ ABT_future_wait()