*** 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. The library itself provides only
5 local (sequential) functions. If necessary, the user (or a language
6 implementor who wishes to use futures) can send converse messages
7 across processors, and have their handlers set the future's values.
8
9 \verb#futuresInitialize()#
10
11 This function initializes the futures module. It can deal with
12 repeated (redundant) initializations, without losing information
13 entered after the previous initialization. Currently, 100 distinct
14 future values may be alive at any moment on each processor. This
15 number will be made a parameter to the futuresInitialize function in
16 future versions.
17
18 {\large \bf createFuture}
19
20 \verb#int createFuture()#
21
22 Returns an integer key designating the future-value-holder just
23 created.
24
25
26 {\large \bf setFuture}
27
28 \verb#setFuture(int key, void*pointer)#
29
30 Sets the value of the future indicate by the key to the given pointer.
31 All the threads waiting for the future specified by the key are
32 awakened. (Each such thread, when it resumes, will return from the
33 waitFuture function with the \verb#pointer# as its return value.)
34
35 {\large \bf sendToFuture}
36
37 \verb#sendToFuture(void *m, int key)#
38
39 Makes an entry in the scheduler's queue that will (when scheduled) set
40 the future value, and awaken the waiting threads. This is an
41 asynchronous version of \verb#setFuture#. 
42
43
44 {\large \bf  waitFuture}
45
46 \verb#void* waitFuture (int key, int free)#
47
48 The caller for this function must be a thread. If the future value is
49 ready (i.e. set by \verb#setFuture# or \verb#sendToFuture#), the
50 function returns immediately with a pointer to the value. Otherwise,
51 the calling thread suspends, and the call returns after another thread
52 has set the future value. This call can be made before or after the future
53 is set.
54
55 destroyFuture(int key)
56
57 Allows  the key to be used for other futures.
58
59 {\large \bf Bugs:} Currently, the number of futures is limited to 100.
60 Although you can reuse a key with destroyFuture, this limits the
61 number of futures alive at a time to 100. With a hash table
62 implementation this could be completely eliminated in a future
63 release, or at least an ability to change the number of available keys
64 at the initialization time will be added.
65