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.
| 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] | compartments | number of compartments in the future |
| [in] | cb_func | callback function to be called once the future is ready |
| [out] | newfuture | handle to a new future |
- Returns
- Error code
- Return values
-
Definition at line 56 of file futures.c.
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] | future | handle to the future |
- Returns
- Error code
- Return values
-
Definition at line 88 of file futures.c.
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] | future | handle to the target future |
- Returns
- Error code
- Return values
-
Definition at line 334 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] | future | handle to the future |
| [in] | value | pointer to the memory buffer containing the data that will be pointed by one compartment of the future |
- Returns
- Error code
- Return values
-
Definition at line 251 of file futures.c.
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] | future | handle to the future |
| [out] | flag | ABT_TRUE if future is ready; otherwise, ABT_FALSE |
- Returns
- Error code
- Return values
-
Definition at line 217 of file futures.c.
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] | future | handle to the future |
- Returns
- Error code
- Return values
-
Definition at line 127 of file futures.c.
1.8.11
