*** empty log message ***
[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).  Caution: CfutureWait can only
28 be done on the processor where the Cfuture resides.  A second caution:
29 blocking operations (such as this one) can only be done in
30 user-created threads.
31
32 {\bf void CfutureDestroy(Cfuture f)}
33
34 Frees the space used by the specified Cfuture.  This also frees the
35 value stored in the future.  Caution: this operation can only be done
36 on the processor where the Cfuture resides.
37
38 {\bf void* CfutureCreateValue(int nbytes)}
39
40 Allocates the specified amount of memory and returns a pointer to it.
41 This buffer can be filled with data and stored into a future, using
42 CfutureStoreBuffer below.  This combination is faster than using
43 CfutureSet directly.
44
45 {\bf void CfutureStoreValue(Cfuture fut, void *value)}
46
47 Make a copy of the value and stores it in the future, destroying the
48 original copy of the value.  This may be significantly faster than the
49 more general function, CfutureSet (it may avoid copying).  This
50 function can {\em only} used to store values that were previously
51 extracted from other futures, or values that were allocated using
52 CfutureCreateValue.
53
54 {\bf void CfutureModuleInit()}
55
56 This function initializes the futures module.  It must be called once
57 on each processor, during the handler-registration process (see the
58 Converse manual regarding CmiRegisterHandler).
59