Changes to insert a section about Futures in the manual.
authorEsteban Meneses <emenese2@illinois.edu>
Tue, 14 Jun 2011 21:27:29 +0000 (16:27 -0500)
committerEsteban Meneses <emenese2@illinois.edu>
Tue, 14 Jun 2011 21:27:29 +0000 (16:27 -0500)
doc/charm++/Makefile
doc/charm++/futures.tex [new file with mode: 0644]
doc/charm++/manual.tex

index 15672e73b1e7e97a9ba163d7760500a7be9575e6..7654688d539dd1e9f5adf5c6888417db0ce8ba01 100644 (file)
@@ -2,7 +2,7 @@
 FILE=manual
 TEX=$(FILE).tex arrays.tex callbacks.tex chares.tex commlib.tex delegation.tex \
        entry.tex further.tex groups.tex inhertmplt.tex index.tex intro.tex \
-       io.tex loadb.tex advancedlb.tex \
+       io.tex loadb.tex advancedlb.tex futures.tex \
        marshalling.tex messages.tex modules.tex nodegroups.tex othercalls.tex \
        overview.tex pup.tex quiesce.tex readonly.tex reductions.tex sdag.tex \
        python.tex
diff --git a/doc/charm++/futures.tex b/doc/charm++/futures.tex
new file mode 100644 (file)
index 0000000..0e131a8
--- /dev/null
@@ -0,0 +1,58 @@
+\subsection{Futures}
+
+\label{futures}
+
+Similar to Multilisp and other functional programming languages, \charmpp\ provides the abstraction of {\em futures}. In simple terms, a {\em future} is a contract with the runtime system to evaluate an expression asynchronously with the calling program. This mechanism promotes the evaluation of expressions in parallel as several threads concurrently evaluate the futures created by a program.
+
+In some ways, a future resembles lazy evaluation. Each future is assigned to a particular thread (or to a chare, in \charmpp\ ) and its value will be eventually delivered to the calling program. Once the future is created, a reference is returned immediately. If the value is needed, however, the calling program blocks until the value is available.
+
+\charmpp\ provides all the necessary infrastructure to use futures by means of the following functions: 
+
+\begin{alltt}
+ CkFuture CkCreateFuture(void)
+ void CkReleaseFuture(CkFuture fut)
+ int CkProbeFuture(CkFuture fut)
+ void *CkWaitFuture(CkFuture fut)
+ void  CkSendToFuture(CkFuture fut, void *msg)
+\end{alltt}
+
+To illustrate the use of all these functions, a Fibonacci example in \charmpp\ using futures in presented below:
+
+\begin{alltt}
+chare fib \{
+  entry fib(int amIroot, int n, CkFuture f);
+  entry  [threaded] void run(int amIroot, int n, CkFuture f);
+\};
+\end{alltt}
+
+\begin{alltt}
+void  fib::run(int AmIRoot, int n, CkFuture f) \{
+   if (n< THRESHOLD)
+    result =seqFib(n);
+  else \{
+    CkFuture f1 = CkCreateFuture();
+    CkFuture f2 = CkCreateFuture();
+    CProxy_fib::ckNew(0,n-1,  f1);
+    CProxy_fib::ckNew(0,n-2,  f2);
+    ValueMsg * m1 = (ValueMsg *) CkWaitFuture(f1);
+    ValueMsg * m2 = (ValueMsg *) CkWaitFuture(f2);
+    result = m1->value + m2->value;
+    delete m1; delete m2;
+  \}
+  if (AmIRoot) \{
+    CkPrintf("The requested Fibonacci number is : \%d\\n", result);
+    CkExit();  
+  \} else \{
+    ValueMsg *m = new ValueMsg();
+    m->value = result;
+    CkSendToFuture(f, m); 
+  \}
+\}
+\end{alltt}
+
+The constant {\em THRESHOLD} sets a limit value for computing the Fibonacci number with futures or just with the sequential procedure. Given value {\em n}, the program creates two futures using {\em CkCreateFuture}. Those futures are used to create two new chares that will carry on the computation. Next, the program blocks until the two values of the Fibonacci's recurrence have been evaluated. Function {\em CkWaitFuture} is used for that purpose. Finally, the program checks whether it is the root of the evaluation or not. The very first chare created with a future is going to be the root. If a chare is not a root, it must indicate its future has finished computing the value. {\em CkSendToFuture} is meant to return the value for the current future.
+
+Other functions complete the API for futures. {\em CkReleaseFuture} destroys a future. {\em CkProbeFuture} test if the future has already finished computing the value of the expression.
+
+The \converse\ version of future functions can be found in the \converse\ \htmladdnormallink{manual}{http://charm.cs.illinois.edu/manuals/html/convext/manual.html}.
+
index 07896cd2d10d9dd4b3be1f016c1b8095f0d8d566..5d096abbe12b56b5ddb3c2cc62b3fc84fd0e5ca1 100644 (file)
@@ -92,6 +92,7 @@
   \input{nodegroups}
   \input{loadb}
   \input{advancedlb}
+  \input{futures}
   \input{quiesce}
   \input{reductions}
   \input{callbacks}