ARGOBOTS  1.1
Typedefs | Functions
Future

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 980 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_compartmentsnumber of compartments of the future
[in]cb_funccallback function to be called when the future is ready
[out]newfuturefuture 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]futurefuture handle
Returns
Error code

Definition at line 116 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]futurefuture handle
Returns
Error code

Definition at line 323 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]futurefuture handle
[in]valuevalue set to one of the compartments of future
Returns
Error code

Definition at line 258 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]futurehandle to the future
[out]is_readyABT_TRUE if future is ready; otherwise, ABT_FALSE
Returns
Error code

Definition at line 220 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]futurefuture handle
Returns
Error code

Definition at line 165 of file futures.c.