3cf2cdc89e489fbfa1be5bb7b273fb733ca2ce84
[charm.git] / doc / convext / futures.tex
1 \chapter{Futures}
2
3 This library supports the {\em future} abstraction, defined and used by
4 Halstead and other researchers.
5
6
7 {\bf Cfuture CfutureCreate()}
8
9 Returns the handle of an empty future.  The future is said to reside
10 on the processor that created it.  The handle is a {\em global}
11 reference to the future, in other words, it may be copied freely
12 across processors.  However, while the handle may be moved across
13 processors freely, some operations can only be performed on the
14 processor where the future resides.
15
16 {\bf Cfuture CfutureSet(Cfuture future, void *value, int nbytes)}
17
18 Makes a copy of the value and stores it in the future.  CfutureSet
19 may be performed on processors other than the one where the future
20 resides.  If done remotely, the copy of the value is created on the
21 processor where the future resides.
22
23 {\bf void *CfutureWait(Cfuture fut)}
24
25 Waits until the future has been filled, then returns a pointer to the
26 contents of the future.  If the future has already been filled, this
27 happens immediately (without blocking).  If the destroy flag is set,
28 the future is destroyed (freed) in the process.  The pointer returned
29 by CfutureWait must eventually be freed using CfutureDestroyValue
30 below.  Caution: CfutureWait can only be done on the processor where
31 the Cfuture resides.  A second caution: blocking operations (such as
32 this one) can only be done in user-created threads.
33
34 {\bf void CfutureDestroy(Cfuture f)}
35
36 Frees the space used by the specified Cfuture.  This also frees the
37 value stored in the future.  Caution: this operation can only be done
38 on the processor where the Cfuture resides.
39
40 {\bf void* CfutureCreateValue(int nbytes)}
41
42 Allocates the specified amount of memory and returns a pointer to it.
43 The memory can be freed by CfutureDestroyValue, just as if it had been
44 extracted from a future.  It can also be filled with data and stored
45 into a future, using CfutureStoreBuffer below.
46
47 {\bf void CfutureStoreValue(Cfuture fut, void *value)}
48
49 Make a copy of the value and stores it in the future, destroying the
50 original copy of the value.  This may be significantly faster than the
51 more general function, CfutureSet (it may avoid copying).  This
52 function can {\em only} used to store values that were previously
53 extracted from other futures, or values that were allocated using
54 CfutureCreateValue.
55
56 {\bf void CfutureModuleInit()}
57
58 This function initializes the futures module.  It must be called once
59 on each processor, during the handler-registration process (see the
60 Converse manual regarding CmiRegisterHandler).
61