From: <jsa...@us...> - 2008-11-12 16:40:24
|
Revision: 87 http://flexotask.svn.sourceforge.net/flexotask/?rev=87&view=rev Author: jsauerbach Date: 2008-11-12 16:40:13 +0000 (Wed, 12 Nov 2008) Log Message: ----------- Programmer's guide further progress: documentation of template API and other cleanups and improvements. Modified Paths: -------------- trunk/flexotask/doc/flexotaskProgramming.html Modified: trunk/flexotask/doc/flexotaskProgramming.html =================================================================== --- trunk/flexotask/doc/flexotaskProgramming.html 2008-11-11 20:26:31 UTC (rev 86) +++ trunk/flexotask/doc/flexotaskProgramming.html 2008-11-12 16:40:13 UTC (rev 87) @@ -41,11 +41,14 @@ <li><a href="#testingRuntime">Testing and Using the Real-Time Runtime</a> </ul> <li><a href="#templates">Constructing Templates</a> +<ul> +<li><a href="#templateAPI">The Template API</a> +</ul> <li><a href="#tasks">Writing Flexotasks</a> </ul> </ul> -<h2><a name="post-install"></a>Post-Install Testing</h2> +<br><hr><br><h2><a name="post-install"></a>Post-Install Testing</h2> <p>Everyone should perform this step to ensure that Flexible Task Graphs have been correctly installed. @@ -73,7 +76,7 @@ that the <b>JUnit</b> view eventually shows (after about a minute) that all tests ran successfully. -<h2><a name="papers"></a>Relevant papers</h2> +<br><hr><br><h2><a name="papers"></a>Relevant papers</h2> <p>The Flexible Task Graph systems is described in a paper in LCTES 2008, and the four programming models that it consolidates are each @@ -101,7 +104,7 @@ R. Guerraoui, J. Vitek, published in OOPSLA 2007 </ul> -<h2><a name="samples"></a>The Samples</h2> +<br><hr><br><h2><a name="samples"></a>The Samples</h2> <p>The <b>flexotask-functiontest</b> project will run as a JUnit test for quick verification after system changes, but it is deliberately @@ -110,7 +113,7 @@ occupies a package. The procedure for creating this project is described under <a href="#post-install">post-install testing</a>. -<h3><a name="pendulum"></a>The Inverted Pendulum example from the +<br><hr><br><h3><a name="pendulum"></a>The Inverted Pendulum example from the LCTES 2007 Exotasks Paper</h3> <p>The package for this example is called <b>lctes2007</b> The example @@ -174,7 +177,7 @@ Flexotask editor to complete the example. This limitation may be removed soon if someone wants to work on eliminating it. -<h3><a name="modes"></a>A Multiple Mode Example also illustrating +<br><hr><br><h3><a name="modes"></a>A Multiple Mode Example also illustrating Simple Parameters</h3> <p>The <b>modes</b> example illustrates the more advanced of the two @@ -211,7 +214,7 @@ class) but they use the parameter as an <b>Integer</b> comparand to cause the two predicates to perform different tests. -<h3><a name="communicating"></a>A Weakly Isolated Task Graph +<br><hr><br><h3><a name="communicating"></a>A Weakly Isolated Task Graph (Communicating Parameters)</h3> <p>The <b>communicating</b> example is an example of how a Flexible @@ -239,7 +242,7 @@ href="com/ibm/realtime/flexotask/tools/FlexotaskXMLParser.html">FlexotaskXMLParser</a> class programmatically. -<h3><a name="types"></a>An Example for Experimenting with allowed Data Types</h3> +<br><hr><br><h3><a name="types"></a>An Example for Experimenting with allowed Data Types</h3> <p>The <b>types</b> example illustrates that both <b>ArrayList</b> and <b>HashMap</b> are acceptable types to be passed between Flexotasks @@ -251,13 +254,13 @@ transmitted between the two Flexotasks. <p>This example also illustrates that a <a -href="com/ibm/realtime/flexotask/template/FlexotaskTemplate.html">FlexotaskTemplate</a> +href="com/ibm/realtime/flexotask/template/package-summary.html">FlexotaskTemplate</a> can be built up programmatically (the <b>Generator</b> classes in the <b>lctes2007</b> and <b>modes</b> examples do this internally). The <b>Main</b> class of this example constructs the graph directly and then validates it. The editor and XML parser were not used anywhere in the development cycle. -<h3><a name="highfreq"></a>The High Frequency Reader Example from the LCTES 2008 Paper</h3> +<br><hr><br><h3><a name="highfreq"></a>The High Frequency Reader Example from the LCTES 2008 Paper</h3> <p>The <b>highfreqread</b> example closely resembles the code used to collect the data for Section 5.1 of our Flexible Task Graphs paper @@ -289,12 +292,12 @@ running in the same virtual machine with the task graph. </ul> -<h2><a name="application"></a>Notes for Application Programmers</h2> +<br><hr><br><h2><a name="application"></a>Notes for Application Programmers</h2> <p>This section provides information that is of use for writing and testing actual Flexotask applications. -<h3><a name="simReal"></a>Simulated and real-time execution modes</h3> +<br><hr><br><h3><a name="simReal"></a>Simulated and real-time execution modes</h3> <p>When you test a Flexotask program under Eclipse, you are running in "simulated" mode. That is, @@ -341,7 +344,8 @@ <p><img width=441 height=136 src="runtimeExportError.jpg"></p> <p>This means you do not have the plugin to generate the parts of the -runtime needed for real-time execution. Follow the procedure in <a +runtime needed for real-time execution. Choose <b>Cancel</b>, then +cancel the main export wizard and follow the procedure in <a href="#obtainingJ9Bridge">the next subsection</a>. <p>If you do have the necessary IBM support, you will get something @@ -366,7 +370,7 @@ <a href="#testingRuntime">below</a> which also provides general information about running programs in the real-time execution mode. -<h4><a name="obtainingJ9Bridge"></a>Obtaining the Runtime to +<br><hr><br><h4><a name="obtainingJ9Bridge"></a>Obtaining the Runtime to Use with IBM WebSphere Real Time</h4> <p>This procedure is only necessary if you installed Flexible Task @@ -377,7 +381,7 @@ <p>Use the Eclipse Update Manager to obtain the support. The procedure differs somewhat between Eclipse 3.3.x and Eclipse 3.4.x. -<h5>Obtaining the IBM Runtime using Eclipse 3.3.x</h5> +<br><hr><br><h5>Obtaining the IBM Runtime using Eclipse 3.3.x</h5> <p><p>Select <b>Help→Software Updates→Find And Install</b>, then select <b>Search For New Features to Install</b> and @@ -387,7 +391,7 @@ <b>Flexible Task Graphs Runtime for IBM WebSphere Real Time</b> and select it. Complete the dialog to install the feature. -<h5>Obtaining the IBM Runtime using Eclipse 3.4.x</h5> +<br><hr><br><h5>Obtaining the IBM Runtime using Eclipse 3.4.x</h5> <p><p>Select <b>Help→Software Updates</b>, then select the <b>Available Software</b> tab. If you don't see the update site @@ -398,7 +402,7 @@ <b>Flexible Task Graphs Runtime for IBM WebSphere Real Time</b> and select it. Complete the dialog to install the feature. -<h4><a name="obtainingWRT"></a>Obtaining The IBM WebSphere Real Time VM Itself</h4> +<br><hr><br><h4><a name="obtainingWRT"></a>Obtaining The IBM WebSphere Real Time VM Itself</h4> <p>You can download copies of the IBM WebSphere Real Time VM from <a href="http://www.ibm.com/developerworks/java/jdk/linux/download.html">IBM @@ -409,14 +413,13 @@ you choose the Java 6 version, note that you must use the "WebSphere Real Time" product, <em>not</em> the "WebSphere Soft Real Time" product. Flexotask support for the soft real time product may be -offered in the future. +offered in the future. Our supplied runtime will also +work with some still-older versions of WRT (Version 1 SR1 and SR2) if +you have obtained these at an earlier time. <p>The Flexible Task Graphs code was most extensively tested with -Version 1 SR3 but we are working to achieve equivalent results on -Version 2 and it mostly seems to work. Our supplied runtime will also -work with some still-older versions of WRT (Version 1 SR1 and SR2) if -you have obtained these at an earlier time. However, we will not -spend much effort debugging on those versions. +Version 1 SR3 but the same functionality appears to work on Version 2 +and we will emphasize support for the latest version in the long run. <p>To use WRT effectively with these releases you need a Linux kernel at version 2.6.21 or later. Version 2 of WRT was tested with Red Hat @@ -425,12 +428,13 @@ will work if they have the real-time capabilities (the suffix -rt indicates this). -<h4><a name="testingRuntime"></a>Testing and Using the Real-Time Runtime</h4> +<br><hr><br><h4><a name="testingRuntime"></a>Testing and Using the Real-Time Runtime</h4> <p>The <b>flexotask-functiontest</b> project provides a script for -packing the necessary tests into a <b>jar</b> file. Locate the file -<b>export.xml</b>, right click and select <b>Run As→Ant -Build</b>. Refresh the project and find the file +packaging itself as a <b>jar</b> file so that you can repeat the same +JUnit tests that you ran under Eclipse, this time using a real-time +VM. Locate the file <b>export.xml</b>, right click and select <b>Run +As→Ant Build</b>. Refresh the project and find the file <b>flexotaskFunctionTest.jar</b>. Copy this file to the Linux machine on which you have IBM WebSphere Real Time installed and to which you exported your Flexotask runtime. @@ -463,9 +467,315 @@ <p>This example should be readily extended to running your own programs. -<h3><a name="templates"></a>Constructing Templates</h3> +<br><hr><br><h3><a name="templates"></a>Constructing Templates</h3> -<h3><a name="tasks"></a>Writing Flexotasks</h3> +<p>A Flexible Task Graph starts out its life as a <em>template</em> +which is then validated and instantiated by the system. The template +describes +<ol> +<li>the tasks that will make up the task graph (at least one) +<li>the input and output <em>ports</em> of those tasks (if any) +<li>the connections between the ports (if any) +<li>the Java classes that implement each task +<li>(optionally) a parameter to use as part of the initialization of each task +</ol> +The template as a whole, plus the specification of each task, port, +and connection, has certain properties that can assume certain values. +Some (but not all) of these properties are <em>timing annotations</em> +whose syntax depends on the selected <em>timing grammar</em> for the +template. +<p>Templates have both an XML representation and a runtime +representation as a tree of Java classes. There are at present three +scenarios for creating templates and making them available at runtime. + +<ol> +<li>The runtime representation of a template can be created +programmatically using the API provided by the <a +href="com/ibm/realtime/flexotask/template/package-summary.html">com.ibm.realtime.flexotask.template</a> +package. This approach is suitable for small simple graphs, +particularly single-task graphs. + +<li>A template can be created with the Flexotask Editor, saved as XML, +and then converted by the <a +href="com/ibm/realtime/flexotask/tools/FlexotaskXMLParser.html#main(java.lang.String[])">FlexotaskXMLParser +main program</a> into Java source. The Java source is then compiled +into a class whose static <b>generateGraph()</b> method is invoked to +create the runtime representation of the template. This approach is +suitable for large task graphs, especially when the target virtual +machine is an embedded system that lacks an XML parser. + +<li>A template can be created with the Flexotask Editor, saved as XML, +and then parsed directly from XML to the runtime representation using +the <b>parse</b>, <b>parsefile</b>, <b>parseStream</b>, or +<b>parseString</b> method of <a +href="com/ibm/realtime/flexotask/tools/FlexotaskXMLParser.html">FlexotaskXMLParser</a>. +This approach is the most straightforward for large task graphs when +the target system has an XML parser. +</ol> + +<br><hr><br><h4><a name="templateAPI"></a>The Template API</h4> + +<p>For fast reference to subsections, use this outline. +<ul> +<li><a href="#templateGlobal">Template Global Properties</a> +<li><a href="#templateTasks">Adding Tasks to a Template</a> +<li><a href="#templatePorts">Adding Ports to a Task</a> +<li><a href="#templatePredicates">Adding Predicates to a Template</a> +<li><a href="#templateCommunicators">Adding Communicators to a Template</a> +<li><a href="#templateConnections">Adding Connections to a Template</a> +</ul> + +<p>To begin the construction of a template, use <b>new +FlexotaskTemplate()</b>. From this starting point, you add global +properties, tasks, and connections. Tasks include normal tasks, +predicates, and communicators. + +<br><hr><br><h5><a name="templateGlobal"></a>Template Global Properties</h5> + +<p>Methods that manipulate global properties include +<ul> +<li><b>setAllocating</b> to establish whether tasks of the graph are allowed to allocate (default is <b>true</b>) + +<li><b>setStableMode</b> to establish how storage in the task's private memory area is to be partitioned +into stable and transient areas (default is to make all storage stable, as in the Exotasks model) + +<li><b>setSynchronizing</b> to establish whether tasks of the graph +are allowed to use Java synchronized methods and blocks (default is +<b>true</b>, but if the graph is strongly isolated, then the +synchronization will have no effect). + +<li><b>setTimingData</b> to establish the timing grammar for the graph +and any global properties that go with that timing grammar. More on +this below. +</ul> + +There is more detail on these options <a +href="com/ibm/realtime/flexotask/template/FlexotaskTemplate.html">in +the javadoc</a>. + +<p>An additional global property of a template is whether the +resulting graph is weakly or strongly isolated. There is no API for +setting or interrogating this property. Instead, the property is +inferred from task properties. If any task in the graph is weakly +isolated, then the graph is weakly isolated. If all tasks of the +graph are strongly isolated, then the graph is strongly isolated. + +<p>The <b>TimingData</b> property of a template must be set if the +template is to be schedulable. The argument to <b>setTimingData</b> +must be a class that extends <a +href="com/ibm/realtime/flexotask/timing/FlexotaskGlobalTimingData.html">FlexotaskGlobalTimingData</a>. +Note that <em>all</em> of the methods defined in the abstract parent class are +for use by aspects of the implementation: all of the "interesting" +information is determined by the particular concrete implementation that you +choose. In the core Flexible Task Graphs system, we provide <a +href="com/ibm/realtime/flexotask/timing/simple/Period.html">Period</a> +and <a +href="com/ibm/realtime/flexotask/timing/simple/ModeList.html">ModeList</a>, +both of which cause one of the built-in <em>time triggered</em> timing +grammars to apply to the rest of template. The former assigns a +period of execution to the entire graph. The latter establishes one +or more <em>modes</em>, each of which has its own period and contains +a subset of the tasks in the graph. Other timing grammars exist and +will (we hope) become available as plugins. These include a streaming +grammar developed by Jesper Spring as part of his thesis at EPFL, a +PTIDES grammar being developed by Jia Zou and Edward Lee at UC +Berkeley, and an HTL grammar originally developed for Exotasks by +Daniel Iercan at the University of Salzburg, which is in the process +of being converted into a Flexotask timing grammar. + +<br><hr><br><h5><a name="templateTasks"></a>Adding Tasks to a Template</h5> + +<p>Most generally, tasks may be "normal" tasks, predicates or +communicators. This section describes how to add normal tasks. +Predicates and communicators are discussed separately. + +<p>To add a normal task, first create a default, empty, <a +href="com/ibm/realtime/flexotask/template/FlexotaskTaskTemplate.html">FlexotaskTaskTemplate</a> +with <b>new FlexotaskTaskTemplate()</b>. Finish initializing it, then +add it to the <b>Set</b> obtained by calling <a +href="com/ibm/realtime/flexotask/template/FlexotaskTemplate.html#getTasks()">getTasks()</a> +on the main template. In a Java 1.5 (or later) project, <b>getTasks()</b> +returns a <b>Set<FlexotaskTaskTemplate></b> instead of a raw +<b>Set</b>. + +<p>A task has properties, and optionally input and output ports. Each +port has some properties. + +<p>Task global properties are as follows. +<ul> +<li><b>setName</b> establishes a name for the task. Every task in a +Flexible Task Graph must have a unique name. + +<li><b>setImplementationClass</b> establishes the implementation class +for the task. The argument is a String but it must name a class that +implements <a +href="com/ibm/realtime/flexotask/Flexotask.html">Flexotask</a> (either +directly or by implementing a subinterface or by extending another +class, which might be the special abstract class <a +href="com/ibm/realtime/flexotask/AtomicFlexotask.html">AtomicFlexotask</a>). + +<li><b>setParameterType</b> establishes the type of a default +parameter that will be declared statically as part of the template and +passed to the task's <b>initialize</b> method if (and only if) no +parameter is supplied at runtime via the parameter map + +<li><b>setParameterValue</b> establishes the value of a default +parameter whose type is given by <b>setParameterType</b>. + +<li><b>setWeaklyIsolated</b> establishes whether the task is strongly +or weakly isolated. The default (contradicting what is stated in the +paper) is strong isolation (this may change in the future). + +<li><b>setTimingData</b> establishes a timing annotation for the task. +More on this below. +</ul> +There is more detail on these options <a +href="com/ibm/realtime/flexotask/template/FlexotaskTaskTemplate.html">in +the javadoc</a>. + +<p>The <b>ParameterType</b> and <b>ParameterName</b> properties form a +pair; if one is specified, both must be specified. + +<p>Not all tasks necessarily need timing annotations. Whether they +need them, and what timing annotation to use, is determined by the +timing grammar (which is, in turn determined by the +<b>setTimingData</b> call on the main template). A timing annotation +applied to a task or connection must extend <a +href="com/ibm/realtime/flexotask/timing/FlexotaskTimingData.html">FlexotaskTimingData</a>. +As is the case with the global timing data, all of the interesting +properties are determined by the timing grammar. With the time +triggered grammars, the only annotation that can apply to a normal +task is <a +href="com/ibm/realtime/flexotask/timing/simple/SimpleTimingAnnotation.html">SimpleTimingAnnotation</a>. +The simplest usage is to assign exactly one time offset to the task +using <b>new SimpleTimingAnnotation(offset)</b> but the javadoc +describes some more advanced options. + +<br><hr><br><h5><a name="templatePorts"></a>Adding Ports to a Task</h5> + +<p>The least error-prone way to specify ports programmatically is as follows. + +<ol> +<li>Create a <a +href="com/ibm/realtime/flexotask/template/FlexotaskPortTemplate.html">FlexotaskPortTemplate</a> +for each port. + +<li>Set the name, type, and buffering properties of each port via its +template. The type is required. Buffering defaults to <b>false</b> +(unbuffered). The name defaults to a system generated name based on +the type of port and its index position amongst the ports of the task. + +<li>Create the array of input port templates in the desired index +order and add it to the task template by calling <a +href="com/ibm/realtime/flexotask/template/FlexotaskTaskTemplate.html#setInputPorts(com.ibm.realtime.flexotask.template.FlexotaskPortTemplate[])">the +<b>setInputPorts</b> function for that form of argument</a>. + +<li>Do the same with the output ports, calling <b>setOutputPorts</b> +instead. +</ol> + +<p>There are also convenience forms of <a +href="com/ibm/realtime/flexotask/template/FlexotaskTaskTemplate.html#setInputPorts(java.lang.String[],%20boolean[],%20java.lang.String[])">setInputPorts</a> +and <b>setOutputPorts</b> that bypass the creation of port templates. +These can be used when the number of ports is small and most port +names and buffering attributes are defaulted. + +<br><hr><br><h5><a name="templatePredicates"></a>Adding Predicates to a Template</h5> + +<p>To add a predicate task, first create a default, empty, <a +href="com/ibm/realtime/flexotask/template/FlexotaskPredicateTemplate.html">FlexotaskPredicateTemplate</a> +with <b>new FlexotaskPredicateTemplate()</b>. Finish initializing it, then, since a predicate is a task, +add it to the <b>Set</b> obtained by calling <a +href="com/ibm/realtime/flexotask/template/FlexotaskTemplate.html#getTasks()">getTasks()</a> +on the main template. In a Java 1.5 (or later) project, <b>getTasks()</b> +returns a <b>Set<FlexotaskTaskTemplate></b> instead of a raw +<b>Set</b>. A predicate template is a subclass of task template. + +<p>A predicate may not have output ports, and its implementation class +must implement <a +href="com/ibm/realtime/flexotask/FlexotaskPredicate.html">FlexotaskPredicate</a> +Otherwise, the initialization of a predicate template follows the same +pattern as a task template. + +<p>The timing data for a predicate will often differ from that of a +normal task because predicates are intended to affect the scheduler. +In the TT timing grammar, predicates must be assigned a <a +href="com/ibm/realtime/flexotask/timing/simple/SimpleModeSwitch.html">SimpleModeSwitch</a> +annotation so that the predicate can assume its expect role in +controlling mode switches. + +<br><hr><br><h5><a name="templateCommunicators"></a>Adding Communicators to a Template</h5> + +<p>To add a communicator task, first create a default, empty, <a +href="com/ibm/realtime/flexotask/template/FlexotaskCommunicatorTemplate.html">FlexotaskCommunicatorTemplate</a> +with <b>new FlexotaskCommunicatorTemplate()</b>. Finish initializing +it, then, since a communicator is a task, add it to the <b>Set</b> +obtained by calling <a +href="com/ibm/realtime/flexotask/template/FlexotaskTemplate.html#getTasks()">getTasks()</a> +on the main template. In a Java 1.5 (or later) project, <b>getTasks()</b> +returns a <b>Set<FlexotaskTaskTemplate></b> instead of +a raw <b>Set</b>. A communicator template is a subclass of task +template. + +<p>To initialize a communicator template, <b>setName</b> and +<b>setParameterType</b> <em>must</em> be called, while +<b>setParameterValue</b> and <b>setTimingData</b> <em>may</em> be +called. Most other aspects of task template initialization are +illegal for communicators: the parameter type determines the types of +its two ports and no other ports may be specified. A communicator has +a fixed implementation provided by the system. It is always weakly +isolated and that property cannot be changed. + +<br><hr><br><h5><a name="templateConnections"></a>Adding Connections to a Template</h5> + +<p>To add a connection, first create a default, empty, <a +href="com/ibm/realtime/flexotask/template/FlexotaskConnectionTemplate.html">FlexotaskConnectionTemplate</a> +with <b>new FlexotaskConnectionTemplate()</b>. Finish initializing +it, then add it to the <b>Set</b> obtained by calling <a +href="com/ibm/realtime/flexotask/template/FlexotaskTemplate.html#getConnections()">getConnections()</a> +on the main template. In a Java 1.5 (or later) project, +<b>getConnections()</b> returns a +<b>Set<FlexotaskConnectionTemplate></b> instead of a raw +<b>Set</b>. There is also a convenience constructor that permits the +creation of a connection template in one step, since these templates +are usually created after all the tasks have been specified. + +<p>A connection has the following properties. +<ul> +<li><b>setName</b> provides an optional name for the connection. If +no name is supplied, the system will generate a convenient name. +Connection names are generally only important in diagnostic messages. + +<li><b>setInput</b> (required) establishes the task whose output port +provides the input to the connection + +<li><b>setOutputPortToRead</b> specifies the particular output port of +the input task that should be read. If not specified, the first (or +only) output port is assumed. + +<li><b>setOutput</b> (required) establishes the task whose input port +will receive the output of the connection + +<li><b>setInputPortToWrite</b> specifies the particular input port of +the output task that should be written. If not specified, the first (or +only) input port is assumed. + +<li><b>setConnectionMode</b> specifies how object references are +transmitted on the connection. The three options ("by reference", "by +deep clone" and "hybrid") are described in detail in the description +of the <a +href="com/ibm/realtime/flexotask/template/FlexotaskConnectionMode.html">FlexotaskConnectionMode</a> +class. + +<li><b>setTimingData</b> establishes a timing annotation for the +connection. Not all connections need timing annotations and not all +timing grammars even allow connections to have timing annotations. In +the TT timing grammar, connections can have annotations on the same +basis as tasks. +</ul> + +<br><hr><br><h3><a name="tasks"></a>Writing Flexotasks</h3> + </body> </html> This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |