Author: derek Date: Tue Jun 12 21:24:17 2007 New Revision: 314 Removed: sofaswitch/trunk/callflow/docs/current/validjoinexample.png sofaswitch/trunk/callflow/docs/deathexample.png Modified: sofaswitch/trunk/callflow/docs/chap2.sgml sofaswitch/trunk/callflow/docs/chap3.sgml sofaswitch/trunk/callflow/src/shapelist.cpp sofaswitch/trunk/callflow/src/shapelist.h Log: Tidy up docs to describe death processing, and joining. Add tests to code to check for valid joining & starting of graphs. Modified: sofaswitch/trunk/callflow/docs/chap2.sgml ============================================================================== --- sofaswitch/trunk/callflow/docs/chap2.sgml (original) +++ sofaswitch/trunk/callflow/docs/chap2.sgml Tue Jun 12 21:24:17 2007 @@ -62,7 +62,8 @@ control element to two other places is ambiguous, and is an error. Thus, the left graph depicted in figure <xref xrefstyle="select: labelnumber" linkend="ambiguousconnection"/> is wrong. Further, you will note that the filled circles -indicating a join are drawn +indicating a join are drawn to both control elements. At compile time, the +faulty connection will be detected and reported. <figure id="ambiguousconnection"> <title>Joining of control elements</title> <informaltable frame="all"> @@ -77,13 +78,22 @@ <imagedata fileref="diagrams/GoodJoin.png" align="center" format="PNG"></imagedata> </imageobject></mediaobject> </entry> +<entry> +<mediaobject><imageobject> +<imagedata fileref="diagrams/ValidJoinExample.png" align="center" format="PNG"></imagedata> +</imageobject></mediaobject> +</entry> </row> <row><entry><para> Faulty graph </para></entry> <entry><para> Correct graph -</para></entry></row> +</para></entry> +<entry><para> +Correct graph +</para></entry> +</row> </tbody> </tgroup> </informaltable> @@ -91,7 +101,8 @@ <para> -When Python code generated from the above graph is run, several messages to and +When Python code generated from the graph in figure +<xref xrefstyle="select: labelnumber"linkend="helloworldexample"/> is run, several messages to and from the server. First, there is a message to the server saying that a new entity has been created, but without a specific &sofaswitch; identity. The server supplies a specific &sofaswitch; identity. Then, the identity disappears @@ -282,4 +293,42 @@ happens and this graph is closed down. </para> </sect1> + +<sect1> +<title>Processing issues</title> +<para> We have described how &callflow; uses the twisted module +(<ulink URL="http://twistedmatrix.com/trac"></ulink>) in Python to handle +events. Further, the outcome of this has been stated as +<quote> +processing of events (timers, network packets etc) happens when execution has +moved into a "suspend graph processing" control icon. +</quote> +However, this sentence should be extended to note that +<quote> +all control messages which are sent to remote &sofaswitch; entities are sent +when execution has moved into a "suspend graph processing" control icon. +</quote> +The following figure <xref xrefstyle="select: labelnumber" +linkend="deathexample"/> gives a clear illustration of the order of processing +in &callflow; +<figure id="deathexample"> +<title>The standard "Hello World" example</title> +<mediaobject><imageobject> +<imagedata fileref="diagrams/DeathExample.png" align="center" format="PNG"></imagedata> +</imageobject></mediaobject> +</figure> +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. In fact, the message is queued for sending. The +message is only sent when execution of control items on this graph is +suspended. The third item on this graph causes the id assigned to this +graph to be deleted. Thus, on processing the terminate processing control item +(section <xref xrefstyle="select: labelnumber" linkend="TerminateProcessing">), +the message that was queued for sending is never sent. Perusal of the message +log on the server will show the creation of a new node (this graph) and the +destruction of this node. +</para> </chapter> + + + Modified: sofaswitch/trunk/callflow/docs/chap3.sgml ============================================================================== --- sofaswitch/trunk/callflow/docs/chap3.sgml (original) +++ sofaswitch/trunk/callflow/docs/chap3.sgml Tue Jun 12 21:24:17 2007 @@ -182,7 +182,7 @@ -<sect1> +<sect1 id="TerminateProcessing"> <title>Death - terminate processing of this graph</title> <para> Consider the figure <xref xrefstyle="select: labelnumber" linkend="deathicon"/> which shows the icon Modified: sofaswitch/trunk/callflow/src/shapelist.cpp ============================================================================== --- sofaswitch/trunk/callflow/src/shapelist.cpp (original) +++ sofaswitch/trunk/callflow/src/shapelist.cpp Tue Jun 12 21:24:17 2007 @@ -228,6 +228,38 @@ return true; } +bool MyListShapesExtended::OneStartProcessing() +{ + int countStarts = 0; + MyListShapes::iterator it = begin(); + while (it != end()) { + DndShape *thisShape = it->second; + if (thisShape->GetKind() == DndShape::StartHere) + countStarts++; + it++; + } + + if (countStarts == 1) + return true; + + if (countStarts == 0) { + it = begin(); + while (it != end()) { + DndShape *thisShape = it->second; + thisShape->SetCompileError("No Start Processing control element"); + it++; + } + return false; + } + + it = begin(); + while (it != end()) { + DndShape *thisShape = it->second; + if (thisShape->GetKind() == DndShape::StartHere) + thisShape->SetCompileError("Duplicate Start Processing control element"); + it++; + } +} bool MyListShapesExtended::Compile(wxTextFile & file) { @@ -246,6 +278,8 @@ it++; } + OneStartProcessing(); + /**Second, go through and check all output points link to something. */ bool pointsLinked = true; it = begin(); Modified: sofaswitch/trunk/callflow/src/shapelist.h ============================================================================== --- sofaswitch/trunk/callflow/src/shapelist.h (original) +++ sofaswitch/trunk/callflow/src/shapelist.h Tue Jun 12 21:24:17 2007 @@ -62,6 +62,12 @@ Returns true on success, false on failure.*/ bool Compile(wxTextFile & file); + /**Test for two start processing control items on this graph. If found, mark + both as compile errors, and return false. return false if none are + found. return true if one is found. If None are found, mark all shapes as + in error, as there is no source object for them. */ + bool OneStartProcessing(); + /**Print this shape info to the launching console, for debug purposes */ void PrintContents();