[Aglets-commits] docs manual.tex,1.23,1.24

[Luca F. <cat...@us...>]

Update of /cvsroot/aglets/docs
In directory 23jxhf1.ch3.sourceforge.com:/tmp/cvs-serv16719

Modified Files:
	manual.tex 
Log Message:
Improved the section of the message management.


Index: manual.tex
===================================================================
RCS file: /cvsroot/aglets/docs/manual.tex,v
retrieving revision 1.23
retrieving revision 1.24
diff -u -d -r1.23 -r1.24
--- manual.tex	1 Apr 2009 07:57:14 -0000	1.23
+++ manual.tex	1 Apr 2009 12:06:49 -0000	1.24
@@ -4003,7 +4003,10 @@
 
 The \texttt{FutureReply} is an abstract class that is used to handle asynchronous replies. When an agent
 sends a message to another agent, it waits for a future reply, that is the reply to the former message
-that could come later in the execution flow. 
+that could come later in the execution flow. A \texttt{FutureReply} is an object on which sender agent
+synchronizes waiting for a reply from the addressee agent, and all the methods of \texttt{FutureReplyImpl} 
+(the concrete implementation of such class) simply exploit the Java synchronization constructs 
+(\texttt{wait()}, \texttt{notify()}) to synchronize agents and their threads.
 
 An important class, defined as abstract, is the \texttt{MessageManager}. The message manager is used to
 handle incoming messages for a specific agent. Each agent has a message manager associated 
@@ -4072,6 +4075,63 @@
 that will dispatch the message to agents). The \texttt{owner} variable is used to store the
 message being currently dispatched.
 
+
+\subsection{Dispatching messages}
+
+The method \texttt{MessageImpl.handleMessage(..)} is used to make an agent handling
+the message itself. This sounds a little recursive, since to deliver a message to an agent
+the message manager must activate the message, and then the message orders the agent to handles
+itself.
+
+The method implementation is the following:
+
+\begin{small}
+\begin{verbatim}
+public void handle(LocalAgletRef ref) throws InvalidAgletException {
+   FutureReplyImpl f = future;
+   Aglet aglet = ref.aglet;
+   Throwable result_ex = null;
+   boolean handled = false;
+
+   try {
+
+     handled = aglet.handleMessage(this);
+
+   } catch (RuntimeException ex) {
+
+     // was trying to process someting..
+    f.sendExceptionIfNeeded(ex);
+    ex.printStackTrace();
+  } catch (ThreadDeath ex) {
+    f.sendExceptionIfNeeded(ex);
+    throw ex;
+  } catch (Throwable ex) {
+    f.sendExceptionIfNeeded(ex);
+    ex.printStackTrace();
+} 
+finally {
+  if (delegatable == false) {
+    if (handled) {
+      if (defered == false) {
+         f.sendReplyIfNeeded(null);
+      } 
+    } else {
+         f.cancel(toString());
+    } 
+  } 
+ } 
+}
+\end{verbatim}
+\end{small}
+
+
+As readers can see, the method constructs a \texttt{FutureReply} object (in particular
+a \texttt{FutureReplyImpl} object that extends the future reply base class). The core of handling
+the message is the call to the \texttt{handleMessage(..)} that could be overriden by developers.
+After returning from such method, and supposing no exception has been generated, the future reply must
+be adjusted and used appropriately. 
+
+
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%