docs: added text for sync and threaded entry methods
authorAaron Becker <akbecker@gmail.com>
Thu, 2 Aug 2012 23:43:24 +0000 (18:43 -0500)
committerAaron Becker <akbecker@gmail.com>
Thu, 2 Aug 2012 23:44:15 +0000 (18:44 -0500)
doc/charm++/manual.tex
doc/charm++/sync.tex [new file with mode: 0644]
doc/charm++/threaded.tex [new file with mode: 0644]

index ac632d6b618e527e585d681148313c12569b7478..d573976967f4d947868b71c8f44a0f0914711917 100644 (file)
@@ -69,8 +69,8 @@
 
 \chapter{Waiting on Completion}
   \section{Asynchronous Barriers}
-  \section{Threaded Entry Methods}
-  \section{Sync Entry Methods}
+  \input{threaded}
+  \input{sync}
   \input{futures}
   \input{quiesce}
 
diff --git a/doc/charm++/sync.tex b/doc/charm++/sync.tex
new file mode 100644 (file)
index 0000000..90e65ae
--- /dev/null
@@ -0,0 +1,20 @@
+
+\section{Sync Entry Methods}
+\label{sync}
+
+Generally entry methods are invoked asynchronously and return void. Therefore,
+while an entry method may send data back to its invoker, it does so by invoking
+another asynchronous entry method on the invoking chare object.
+
+However, it is possible to use \kw{sync} entry methods, which have blocking
+semantics and can return data back to their invoker that is available when it
+returns from blocking. This returned data must be in the form of a \charmpp
+message. Because the caller of a sync entry method will block, it must execute
+in a thread separate from the scheduler; that is, it must be a \kw{threaded}
+entry method. If a sync entry method returns a value, it is provided as the
+return value from the invocation on the proxy object:
+
+\begin{alltt}
+ ReturnMsg* m;
+ m = A[i].foo(a, b, c);
+\end{alltt}
diff --git a/doc/charm++/threaded.tex b/doc/charm++/threaded.tex
new file mode 100644 (file)
index 0000000..c43d9d6
--- /dev/null
@@ -0,0 +1,17 @@
+\section{Threaded Entry Methods}
+\label{threaded}
+
+Typically, entry methods run in the same thread of execution as the \charmpp
+scheduler. This prevents them from undertaking any actions that would cause
+their thread to block, as blocking would prevent the receiving and processing of
+incoming messages.
+
+However, entry methods with the \kw{threaded} attribute run in their own
+user-level nonpreemptible thread, and are therefore able to block without
+interrupting the runtime system. This allows them to undertake blocking
+operations or explicitly suspend themselves, which is necessary to use some
+\charmpp features, such as sync entry methods and futures.
+
+For details on the threads API available to threaded entry methods, see chapter
+3 of the Converse programming manual. The use of threaded entry methods is
+demonstrated in an example program located in examples/charm++/threaded\_ring.