Author: derek Date: Wed Jun 13 00:35:08 2007 New Revision: 317 Removed: sofaswitch/trunk/callflow/docs/exchildgraph.png sofaswitch/trunk/callflow/docs/exloadnewgraph.png Modified: sofaswitch/trunk/callflow/docs/app1.sgml sofaswitch/trunk/callflow/docs/callflow.xml sofaswitch/trunk/callflow/docs/chap3.sgml sofaswitch/trunk/callflow/tests/child.src sofaswitch/trunk/callflow/tests/loadgraph.src Log: Doc tidyups. Get images looking right. Improve text reporting in the generated graphs. Modified: sofaswitch/trunk/callflow/docs/app1.sgml ============================================================================== --- sofaswitch/trunk/callflow/docs/app1.sgml (original) +++ sofaswitch/trunk/callflow/docs/app1.sgml Wed Jun 13 00:35:08 2007 @@ -56,11 +56,14 @@ Writing callflow.hhc </screen> Once the actual html is generated, the zip file must be created. This zip file -contains the files generated by the <literal>xsltproc</literal> command. On +contains the files generated by the <literal>xsltproc</literal> command and the +image files referenced by the .sgml files. On Unix, the command is <screen> -zip doc.zip *.html *.hh* + find . -name \*.html -or -name \*.hh\* -or -name \*.png | xargs zip doc.zip </screen> +The generated <literal>doc.zip</literal> file must be in the same directory as +where the &callflow; executable is run from. </para> </appendix> Modified: sofaswitch/trunk/callflow/docs/callflow.xml ============================================================================== --- sofaswitch/trunk/callflow/docs/callflow.xml (original) +++ sofaswitch/trunk/callflow/docs/callflow.xml Wed Jun 13 00:35:08 2007 @@ -56,7 +56,6 @@ </book> -<!-- > exchildgraph.png - > exloadnewgraph.png +<!-- > faultyendprocessing.png --> \ No newline at end of file Modified: sofaswitch/trunk/callflow/docs/chap3.sgml ============================================================================== --- sofaswitch/trunk/callflow/docs/chap3.sgml (original) +++ sofaswitch/trunk/callflow/docs/chap3.sgml Wed Jun 13 00:35:08 2007 @@ -824,16 +824,90 @@ <row> <entry><literal>Python variable to pass to the child</literal></entry> <entry><para> -One Python variable (which may be a list) is past to the child graph. This -(typically) would contain the id of &sofaswitch; worker -nodes that are in existance which are available to do any desired task. +One Python variable (which may be a list or tuple) is past to the child +graph. This (typically) would contain the id of &sofaswitch; worker nodes that +are in existance which are available to do any desired task. The child graph +can access this data in the Python variable <literal>self.userData</literal>. </para></entry></row> +</tbody> +</tgroup> +</informaltable> +</para> +<para> +The load new graph control object is crucial to the deployment of large scale +systems, where multiple calls are handled simultaneously. Since one graph is +not sufficient (on its own) to handle the myriad of calls in the one of many +different styles, the user of such large systems needs to have a good +understanding of how this control object works. An additional figure +<xref xrefstyle="select: labelnumber" linkend="loadnewgraphexample"/> is +provided to illustrate the operation. +<figure id="loadnewgraphexample"> +<title>Example of load new graph</title> +<informaltable frame="all"> +<tgroup cols="2"> +<tbody> +<row><entry><para> +<mediaobject><imageobject> + <imagedata fileref="diagrams/exChildGraph.png" align="center" format="PNG"></imagedata> +</imageobject></mediaobject> +</para></entry> +<entry><para> +<mediaobject><imageobject> +<imagedata fileref="diagrams/exLoadNewGraph.png" align="center" format="PNG"></imagedata> +</imageobject></mediaobject> +</para></entry></row> +<row><entry><para>child graph </para></entry> + <entry><para>parent (creator) graph</para></entry></row> </tbody> </tgroup> </informaltable> +</figure> +The left image in figure <xref xrefstyle="select: labelnumber" +linkend="loadnewgraphexample"/> shows the child graph. Multiple copies of this +will be created. The key operation of the child graph is to execute a Python +statement. In this case, the output of the Python statement is to print the +<itemizedlist> + <listitem><para> + <literal>self.myId</literal> (&sofaswitch; ID) of the parent graph. + </para></listitem> + <listitem><para> + <literal>self.myId</literal> (&sofaswitch; ID) of the child graph. + </para></listitem> + <listitem><para> + The for loop variable, which is passed from the parent graph to the child +graph. The child graph receives variables from the parent in the Python +variable <literal>self.userData</literal> + </para></listitem> +</itemizedlist> +</para> +<para> +The parent graph (right image, figure <xref xrefstyle="select: labelnumber" +linkend="loadnewgraphexample"/> shows the parent graph. This graph consists of +a for loop which is designed to create multiple child graphs. On creation of a +child graph, a Python statement is executed, which prints a message about the +for loop variable. After all of the child graphs have been created, a timer is +started and execution is suspended. During the suspended time interval, the +child graphs all run. The eventer control structure captures the event of timer +termination, and the graph is terminated. +</para> +<para> +Output to the console from the parent running is +<programlisting> +have generated the new graph on loop counter 0 +have generated the new graph on loop counter 1 +have generated the new graph on loop counter 2 +CHILD says::: parent id is c69 child id is c71 data from parent is 0 +CHILD says::: parent id is c69 child id is c72 data from parent is 2 +CHILD says::: parent id is c69 child id is c70 data from parent is 1 +end the master now +</programlisting> +Here, the issue of processing order is apparent. You see that the child +processes do not start until the parent has suspended. Further, the order of +the child processes running is not as one would expect. It is based on +decisions about which event is first by the Twisted Python module. </para> </sect1> Modified: sofaswitch/trunk/callflow/tests/child.src ============================================================================== --- sofaswitch/trunk/callflow/tests/child.src (original) +++ sofaswitch/trunk/callflow/tests/child.src Wed Jun 13 00:35:08 2007 @@ -1 +1 @@ -1<B>518<B>50<B> extra <special>Tool Tip<ms>Start Processing<ms><special> <B><Shape>10<B>528<B>93<B> extra <special>Tool Tip<ms>Python<ms><special>Python Code<ms>print "CHILD says::: parent id is ", self.parentId, " user data is ", self.userData<ms><special> <B><Shape>20<B>531<B>142<B> extra <special>Tool Tip<ms>Death<ms><special> <B><Shape> +20<B>531<B>142<B> extra <special>Tool Tip<ms>Death<ms><special> <B><Shape>10<B>528<B>93<B> extra <special>Tool Tip<ms>Python<ms><special>Python Code<ms>print "CHILD says::: parent id is ", self.parentId, " child id is ", self.myId, "data from parent is ", self.userData<ms><special> <B><Shape>1<B>518<B>50<B> extra <special>Tool Tip<ms>Start Processing<ms><special> <B><Shape> Modified: sofaswitch/trunk/callflow/tests/loadgraph.src ============================================================================== --- sofaswitch/trunk/callflow/tests/loadgraph.src (original) +++ sofaswitch/trunk/callflow/tests/loadgraph.src Wed Jun 13 00:35:08 2007 @@ -1 +1 @@ -14<B>393<B>334<B> extra <special>Tool Tip<ms>Eventer<ms><special>Event sought (Python code)<ms><ms><special>Event sought (Regular Exp)<ms>thistimer<ms><special>Python variable: source of the event<ms>self.eventSource<ms><special>Python variable: name of the event<ms>self.eventName<ms><special>Python variable: generated data<ms>self.eventData<ms><special> <B><Shape>9<B>322<B>107<B>374,107,322,107,322,260,372,263<special>Tool Tip<ms>Join blocks shape<ms><special> <B><Shape>2<B>510<B>356<B> extra <special>Tool Tip<ms>End Processing<ms><special> <B><Shape>4<B>372<B>238<B> extra <special>Tool Tip<ms>End For Loop<ms><special> <B><Shape>12<B>381<B>280<B> extra <special>Tool Tip<ms>Timer<ms><special>Timer period (seconds, Python code)<ms>2<ms><special>Timer label (Python code)<ms>"thistimer"<ms><special> <B><Shape>18<B>381<B>127<B> extra <special>Tool Tip<ms>Load New Graph<ms><special>new graph file (Python code)<ms>"child.graph"<ms><special>Python variable to pass to child<ms>self.data[a]<ms><special> <B><Shape>10<B>390<B>181<B> extra <special>Tool Tip<ms>Python<ms><special>Python Code<ms>print "have generated the new graph"<ms><special> <B><Shape>10<B>389<B>373<B> extra <special>Tool Tip<ms>Python<ms><special>Python Code<ms>print "end the master now"<ms><special> <B><Shape>3<B>374<B>82<B> extra <special>Tool Tip<ms>Start For - to make lots of graphs<ms><special>Initialise (Python code)<ms>self.i = 0<ms><special>Test for Termination (Python code)<ms>self.i < 10<ms><special>Increment (Python code)<ms>self.i+=1<ms><special> <B><Shape>20<B>392<B>420<B> extra <special>Tool Tip<ms>Death<ms><special> <B><Shape>1<B>379<B>35<B> extra <special>Tool Tip<ms>Start Processing<ms><special> <B><Shape>9<B>443<B>356<B>443,356,500,356,538,356<special>Tool Tip<ms>Join blocks shape<ms><special> <B><Shape> +10<B>390<B>181<B> extra <special>Tool Tip<ms>Python<ms><special>Python Code<ms>print "have generated the new graph on loop counter", self.i<ms><special> <B><Shape>18<B>381<B>127<B> extra <special>Tool Tip<ms>Load New Graph<ms><special>new graph file (Python code)<ms>"child.graph"<ms><special>Python variable to pass to child<ms>self.i<ms><special> <B><Shape>4<B>372<B>238<B> extra <special>Tool Tip<ms>End For Loop<ms><special> <B><Shape>9<B>322<B>107<B>374,107,322,107,322,260,372,263<special>Tool Tip<ms>Join blocks shape<ms><special> <B><Shape>20<B>392<B>420<B> extra <special>Tool Tip<ms>Death<ms><special> <B><Shape>3<B>374<B>82<B> extra <special>Tool Tip<ms>Start For - to make lots of graphs<ms><special>Initialise (Python code)<ms>self.i = 0<ms><special>Test for Termination (Python code)<ms>self.i < 3<ms><special>Increment (Python code)<ms>self.i+=1<ms><special> <B><Shape>1<B>379<B>35<B> extra <special>Tool Tip<ms>Start Processing<ms><special> <B><Shape>9<B>443<B>356<B>443,356,500,356,538,356<special>Tool Tip<ms>Join blocks shape<ms><special> <B><Shape>2<B>510<B>356<B> extra <special>Tool Tip<ms>End Processing<ms><special> <B><Shape>14<B>393<B>334<B> extra <special>Tool Tip<ms>Eventer<ms><special>Event sought (Python code)<ms><ms><special>Event sought (Regular Exp)<ms>thistimer<ms><special>Python variable: source of the event<ms>self.eventSource<ms><special>Python variable: name of the event<ms>self.eventName<ms><special>Python variable: generated data<ms>self.eventData<ms><special> <B><Shape>12<B>381<B>280<B> extra <special>Tool Tip<ms>Timer<ms><special>Timer period (seconds, Python code)<ms>1<ms><special>Timer label (Python code)<ms>"thistimer"<ms><special> <B><Shape>10<B>389<B>373<B> extra <special>Tool Tip<ms>Python<ms><special>Python Code<ms>print "end the master now"<ms><special> <B><Shape>