ARGOBOTS  1059a7c2eb7e3f99f736a9c3a4f6ea476ac1b804
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups
Functions
Future

Functions

int ABT_future_create (uint32_t compartments, void(*cb_func)(void **arg), ABT_future *newfuture)
 Create a future. More...
 
int ABT_future_free (ABT_future *future)
 Free the future object. More...
 
int ABT_future_wait (ABT_future future)
 Wait on the future. More...
 
int ABT_future_test (ABT_future future, ABT_bool *flag)
 Test whether the future is ready. More...
 
int ABT_future_set (ABT_future future, void *value)
 Signal the future. More...
 
int ABT_future_reset (ABT_future future)
 Reset the readiness of the target future. More...
 

Detailed Description

A future, an eventual, or a promise, is a mechanism for passing a value between threads, allowing a thread to wait for a value that is set asynchronously. It is used to increase concurrency in a parallel program. This construction is really popular in functional programming languages, in particular MultiLisp. If the programmer defines a future containing an expression, the runtime system promises to evaluate that expression concurrently. The resulting value of the expression might not be available immediately, but it will be eventually computed. Therefore, futures also require a synchronization interface between the program and the multiple concurrent threads that may be computing portions of the code.

In Argobots, futures are used with the purpose of synchronizing execution between cooperating concurrent ULTs. There are two basic mechanisms implemented, eventuals and futures.

A future in Argobots has a slightly different behavior. A future is created with a number of compartments. Each of those k compartments will be set by contributing ULTs. Any other ULT will block on a future until all the compartments have been set. In some sense, a future is a multiple-buffer extension of an eventual. Eventuals and futures have a different philosophy of memory management. An eventual will create and destroy the memory buffer that will hold a result. In contrast, a future does not create any buffer. Therefore, a future assumes each contributing ULT allocates and destroys all memory buffers. When a contributing ULT sets a value, it just passes a pointer to the particular memory location.

Function Documentation

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

Create a future.

ABT_future_create creates a future and returns a handle to the newly created future into newfuture. This routine allocates an array with as many compartments as defined. Each compartment consists in a void* pointer. The future has a counter to determine whether all contributions have been made. This routine also creates a list of entries for all the ULTs that will be blocked waiting for the future to be ready. The list is initially empty. The entries in the list are set with the same order as the ABT_future_set are terminated.

Parameters
[in]compartmentsnumber of compartments in the future
[in]cb_funccallback function to be called once the future is ready
[out]newfuturehandle to a new future
Returns
Error code
Return values
ABT_SUCCESSon success

Definition at line 56 of file futures.c.

int ABT_future_free ( ABT_future future)

Free the future object.

ABT_future_free releases memory associated with the future future. It also deallocates the array of compartments of the future. If it is successfully processed, future is set to ABT_FUTURE_NULL.

Parameters
[in,out]futurehandle to the future
Returns
Error code
Return values
ABT_SUCCESSon success

Definition at line 93 of file futures.c.

int ABT_future_reset ( ABT_future  future)

Reset the readiness of the target future.

ABT_future_reset() resets the readiness of the target future future so that it can be reused. That is, it makes future unready irrespective of its readiness.

Parameters
[in]futurehandle to the target future
Returns
Error code
Return values
ABT_SUCCESSon success

Definition at line 299 of file futures.c.

int ABT_future_set ( ABT_future  future,
void *  value 
)

Signal the future.

ABT_future_set sets a value in the future's array. If all the contributions have been received, this routine awakes all ULTs waiting on the future future. In that case, all ULTs waiting on this future will be ready to be scheduled. If there are contributions still missing, this routine will store the pointer passed by parameter value and increase the internal counter.

Parameters
[in]futurehandle to the future
[in]valuepointer to the memory buffer containing the data that will be pointed by one compartment of the future
Returns
Error code
Return values
ABT_SUCCESSon success

Definition at line 228 of file futures.c.

int ABT_future_test ( ABT_future  future,
ABT_bool flag 
)

Test whether the future is ready.

ABT_future_test is a non-blocking function that tests whether the future future is ready or not. It returns the result through flag.

Parameters
[in]futurehandle to the future
[out]flagABT_TRUE if future is ready; otherwise, ABT_FALSE
Returns
Error code
Return values
ABT_SUCCESSon success

Definition at line 201 of file futures.c.

int ABT_future_wait ( ABT_future  future)

Wait on the future.

ABT_future_wait blocks the caller ULT until the future future is resolved. If the future is not ready, the ULT calling this routine suspends and goes to state BLOCKED. Internally, an entry is created per each blocked ULT to be awaken when the future is signaled. If the future is ready, this routine returns immediately. The system keeps a list of all the ULTs waiting on the future.

Parameters
[in]futurehandle to the future
Returns
Error code
Return values
ABT_SUCCESSon success

Definition at line 125 of file futures.c.