From derek@sofaswitch.org Sun Nov 19 17:01:04 2006
From: SofaSWITCH SVN <derek@sofaswitch.org>
To: sofaswitch-svn@lists.freeswitch.org
Subject:
 [Sofaswitch-svn] [commit] r207 - in sofaswitch/trunk/callflow/docs:	. current
Date: Sun, 19 Nov 2006 17:01:04 -0500
Message-ID: <E1Gluim-0000pc-1N@chaos.freeswitch.org>
MIME-Version: 1.0
Content-Type: multipart/mixed; boundary="===============2445615087542994530=="

--===============2445615087542994530==
Content-Type: text/plain; charset="utf-8"
Content-Transfer-Encoding: quoted-printable

Author: derek
Date: Sun Nov 19 17:01:03 2006
New Revision: 207

Added:
   sofaswitch/trunk/callflow/docs/exloadnewgraph.png   (contents, props chang=
ed)
Modified:
   sofaswitch/trunk/callflow/docs/current/eachicon.dxy

Log:
Add documentation on icons on the screen, and an
explanatory graph.


Modified: sofaswitch/trunk/callflow/docs/current/eachicon.dxy
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D
--- sofaswitch/trunk/callflow/docs/current/eachicon.dxy	(original)
+++ sofaswitch/trunk/callflow/docs/current/eachicon.dxy	Sun Nov 19 17:01:03 2=
006
@@ -8,13 +8,15 @@
=20
 The control structures described in this page are
 \li \ref subsecConditional
+\li \ref subsecDeath
 \li \ref subsecEndCall
 \li \ref subsecEndFor
-\li \ref subsecEndEverything
 \li \ref subsecEndProcessing
 \li \ref subsecEventer
 \li \ref subsecJoinObjects
+\li \ref subsecLoadNewGraph
 \li \ref subsecMakeCall
+\li \ref subsecPython
 \li \ref subsecReadFromFile=20
 \li \ref subsecRequestNode
 \li \ref subsecStartFlow
@@ -61,11 +63,77 @@
=20
=20
=20
+\subsection subsecConditional Conditional execution
+The toolbar icon and a rendering of a drawing area shape for the "Conditiona=
l"
+item is shown below.
+<CENTER><TABLE frame=3Dvoid border=3D0><TR><TD>
+\image html ControlsIf.png
+</TD><TD>
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
+</TD><TD>
+\image html conditional.png
+</TD></TR>
+</TABLE></CENTER>
=20
+On clicking the right mouse button on this shape, a window comes up. The tool
+tip is as described before. The condition, which is evaluated is a Python
+expression. Should this expression not be valid, a message will be printed to
+the display when the compiled code is executed.=20
+=20
+On evaluation of the compiled code, execution switches to the bottom (True
+result) or right output (False result).
=20
=20
=20
+\subsection subsecDeath Death - terminate processing of this graph
+The toolbar icon and a rendering of a drawing area shape for the "Death"
+item is shown below.
+<CENTER><TABLE frame=3Dvoid border=3D0><TR><TD>
+\image html bitmaps/death.png
+</TD><TD>
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
+</TD><TD>
+\image html current/Death.png
+</TD></TR>
+</TABLE></CENTER>
=20
+
+
+
+
+On clicking the right mouse button on this shape, a window comes up. The tool
+tip is as described before.
+=20
+On evaluation of the compiled code, execution of all elements in this graph
+is terminated. All current or pending events are ignored. All outstanding
+timers are ignored.=20
+
+If a worker node was created as part of procesing this graph, the node will
+not be terminated by this item.=20
+
+There are some weird anomalies with this icon that illustrate the actual
+processing of the graph.
+Consider the three item graph in the figure
+\image html deathexample.png
+
+In the first item, a link with the server is created, and an id is assigned =
to
+this graph. The second item causes a message to be sent to some SofaSwitch
+application to request a node. The third item causes the id assigned to this
+graph to be deleted. Of interest is that the request for a new node (from the
+second item) is never sent to the SofaSwitch application. This happens becau=
se
+the Twisted framework (that is used to process this graph) is waiting for
+execution to fall into a \ref subsecEndProcessing item before sending messag=
es
+and handling timer/network events. Since execution fell into this "Death"
+icon, which terminated the connection to the server for this graph, there is
+no way messages can be sent.
+
+
+
+
+
+
+
+
 \subsection subsecEndCall End a call
 End  a call to some external entity is indicated by the toolbar icon and dra=
wing area
 image of =20
@@ -121,22 +189,7 @@
=20
=20
=20
-\subsection subsecEndEverything End Everything
-The toolbar icon and a rendering of a drawing area shape for the "End Everyt=
hing"
-item is shown below.
-<CENTER><TABLE frame=3Dvoid border=3D0><TR><TD>
-\image html bitmaps/death.png
-</TD><TD>
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
-</TD><TD>
-\image html current/Death.png
-</TD></TR>
-</TABLE></CENTER>
=20
-This icon initiates immediate closure of this Python instance. The connection
-to the remote server is severed immediately. All pending TCP messages that we
-were to have sent out are dropped. All pending timer events are
-ignored. Further, processing will not ever return to any part of this graph.
=20
=20
=20
@@ -144,25 +197,15 @@
=20
=20
=20
-
-
-
-
-
-
-
-
-
-
 \subsection subsecEndProcessing End Graph Processing
 The toolbar icon and a rendering of a drawing area shape for the "End Graph =
Processing"
 item is shown below.
 <CENTER><TABLE frame=3Dvoid border=3D0><TR><TD>
-\image html bitmaps/ControlsEndHere.png
+\image html ControlsEndHere.png
 </TD><TD>
 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
 </TD><TD>
-\image html current/endflow.png
+\image html endflow.png
 </TD></TR>
 </TABLE></CENTER>
=20
@@ -289,13 +332,60 @@
=20
=20
=20
+\subsection subsecLoadNewGraph Load new graph
=20
+The toolbar icon and a rendering of a drawing area shape for the "Load New
+Graph" item is shown below.
+<CENTER><TABLE frame=3Dvoid border=3D0><TR><TD>
+\image html newgraph.png
+</TD><TD>
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
+</TD><TD>
+\image html loadnewgraph.png
+</TD></TR>
+</TABLE></CENTER>
=20
+This item provides the means to extend one graph so that it can launch child
+processes. It is similar to the C command "system", except that control
+returns immediately to the parent process and does not wait for execution to
+finish in the child process.
=20
+It is not similar to threads in C, as the child process does not have access
+to the memory of the parent process. Nor is it similar to "fork()" in C, as
+there is no duplication of the parent process.
=20
+On clicking the right mouse button on this shape, a window comes up. The tool
+tip is as described before. We suggest that the tool tip is changed to conta=
in
+a short description of the child process that is to be launched. The second
+box describes the name of the graph file which is to be executed in the child
+process. The third box describes the Python variable which is to be passed to
+the child process.
=20
+As a convenience, the child process always has a Python variable,
+"self.parentId" defined, which contains the id of the child process. The chi=
ld
+may send a message (via the server) to the parent Id indicating status.
=20
+The graph in the figure
+\image html exloadnewgraph.png
+illustrates the operation of this item. There are two event handlers setup,
+and on detection of the specified event, a new graph is loaded and
+processed. Thus, one can handle different incoming calls with different
+graphs. On the third kind of event, the \ref subsecDeath item is handled.
=20
+In a child graph, the terminate processing item will only end that child
+graph, and that child graph Id. In the parent graph, the terminate processing
+item will do one of two things
+\li if the parent graph was directly created by running Python from the
+    command line, the parent and all child graphs are destroyed dead.
+\li if the parent graph is itself a child graph, only the processing of the
+    parent graph is terminated.
+
+
+
+
+
+
+
 \subsection subsecMakeCall Make a call
 Make a call to some external entity is indicated by the toolbar icon and dra=
wing area
 image of =20
@@ -329,7 +419,28 @@
=20
=20
=20
+\subsection subsecPython Python command
+Execution of an arbitrary Python command is indicated by the toolbar icon an=
d drawing area
+image of =20
+<CENTER><TABLE frame=3Dvoid border=3D0><TR><TD>
+\image html Python.png=20
+</TD><TD>
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
+</TD><TD>
+\image html python.png
+</TD></TR>
+</TABLE></CENTER>
=20
+On clicking the right mouse button on this shape, a window comes up. The tool
+tip is as described before. It is suggested that you change the tool tip to
+describe in a couple of words the purpose of the Python code.
+
+The arbitrary Python code which is to be executed is entered in the lower box
+of the displayed window. You have access to all the internal variables used =

+in the execution of this graph. It is possible to simply put a print stateme=
nt
+in there as a debugging technique. It is encouraged that you put short,
+quickly executed statements here, as all other actions are suspended while
+processing this item.
=20
=20
=20

Added: sofaswitch/trunk/callflow/docs/exloadnewgraph.png
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D
Binary file. No diff available.


--===============2445615087542994530==--