Author: derek Date: Sun Nov 19 17:01:03 2006 New Revision: 207 Added: sofaswitch/trunk/callflow/docs/exloadnewgraph.png (contents, props changed) 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 ============================================================================== --- sofaswitch/trunk/callflow/docs/current/eachicon.dxy (original) +++ sofaswitch/trunk/callflow/docs/current/eachicon.dxy Sun Nov 19 17:01:03 2006 @@ -8,13 +8,15 @@ 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 \li \ref subsecRequestNode \li \ref subsecStartFlow @@ -61,11 +63,77 @@ +\subsection subsecConditional Conditional execution +The toolbar icon and a rendering of a drawing area shape for the "Conditional" +item is shown below. +<CENTER><TABLE frame=void border=0><TR><TD> +\image html ControlsIf.png +</TD><TD> +           +</TD><TD> +\image html conditional.png +</TD></TR> +</TABLE></CENTER> +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. + +On evaluation of the compiled code, execution switches to the bottom (True +result) or right output (False result). +\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=void border=0><TR><TD> +\image html bitmaps/death.png +</TD><TD> +           +</TD><TD> +\image html current/Death.png +</TD></TR> +</TABLE></CENTER> + + + + +On clicking the right mouse button on this shape, a window comes up. The tool +tip is as described before. + +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. + +If a worker node was created as part of procesing this graph, the node will +not be terminated by this item. + +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 because +the Twisted framework (that is used to process this graph) is waiting for +execution to fall into a \ref subsecEndProcessing item before sending messages +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 drawing area image of @@ -121,22 +189,7 @@ -\subsection subsecEndEverything End Everything -The toolbar icon and a rendering of a drawing area shape for the "End Everything" -item is shown below. -<CENTER><TABLE frame=void border=0><TR><TD> -\image html bitmaps/death.png -</TD><TD> -           -</TD><TD> -\image html current/Death.png -</TD></TR> -</TABLE></CENTER> -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. @@ -144,25 +197,15 @@ - - - - - - - - - - \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=void border=0><TR><TD> -\image html bitmaps/ControlsEndHere.png +\image html ControlsEndHere.png </TD><TD>            </TD><TD> -\image html current/endflow.png +\image html endflow.png </TD></TR> </TABLE></CENTER> @@ -289,13 +332,60 @@ +\subsection subsecLoadNewGraph Load new graph +The toolbar icon and a rendering of a drawing area shape for the "Load New +Graph" item is shown below. +<CENTER><TABLE frame=void border=0><TR><TD> +\image html newgraph.png +</TD><TD> +           +</TD><TD> +\image html loadnewgraph.png +</TD></TR> +</TABLE></CENTER> +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. +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. +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 contain +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. +As a convenience, the child process always has a Python variable, +"self.parentId" defined, which contains the id of the child process. The child +may send a message (via the server) to the parent Id indicating status. +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. +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 drawing area image of @@ -329,7 +419,28 @@ +\subsection subsecPython Python command +Execution of an arbitrary Python command is indicated by the toolbar icon and drawing area +image of +<CENTER><TABLE frame=void border=0><TR><TD> +\image html Python.png +</TD><TD> +           +</TD><TD> +\image html python.png +</TD></TR> +</TABLE></CENTER> +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 statement +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. Added: sofaswitch/trunk/callflow/docs/exloadnewgraph.png ============================================================================== Binary file. No diff available.