Menu
▾
▴
[flexotask-commits] SF.net SVN: flexotask:[85] trunk/flexotask/doc
|
From: <jsa...@us...> - 2008-11-11 17:30:04
|
Revision: 85
http://flexotask.svn.sourceforge.net/flexotask/?rev=85&view=rev
Author: jsauerbach
Date: 2008-11-11 17:30:00 +0000 (Tue, 11 Nov 2008)
Log Message:
-----------
Update documentation
Modified Paths:
--------------
trunk/flexotask/doc/flexotaskProgramming.html
Added Paths:
-----------
trunk/flexotask/doc/runtimeExportDialog.jpg
trunk/flexotask/doc/runtimeExportError.jpg
Modified: trunk/flexotask/doc/flexotaskProgramming.html
===================================================================
--- trunk/flexotask/doc/flexotaskProgramming.html 2008-11-11 16:12:11 UTC (rev 84)
+++ trunk/flexotask/doc/flexotaskProgramming.html 2008-11-11 17:30:00 UTC (rev 85)
@@ -4,7 +4,468 @@
<title>Flexible Task Graphs Programmer and Developer's Guide</title>
</head>
<body>
-<h1>Flexible Task Graphs Programmer and Developer's Guide</h1>
-<p>Under construction.
+<h1>Flexible Task Graphs Programmer and Developer's Guide</h1>
+
+<p>If you are reading this, you have successfully installed the
+Flexible Task Graphs feature in your Eclipse IDE.
+
+<p>These high level instructions complement the detailed <a
+href="index.html">javadoc</a> for the Flexible Task Graphs API. They
+include sections to support <em>application programming</em> (using
+Flexible Task Graphs to develop real-time Java control applications),
+<em>system extension</em> (writing new schedulers, timing grammars,
+distributers, and instrumentation for Flexible Task Graphs), <em>core
+development</em> (contributing to the evolution of the Flexible Task
+Graphs programming model and its supporting code), and <em>tool
+developement </em> (creating new tools to generate Flexible Task
+Graph templates).
+
+<p>The following outline will help you find relevant information.
+<ul>
+<li><a href="#post-install">Post-Install Testing</a>
+<li><a href="#papers">Relevant Papers</a>
+<li><a href="#samples">The Samples</a>
+<ul>
+<li><a href="#pendulum">The Inverted Pendulum Example from the LCTES 2007 Exotasks Paper</a>
+<li><a href="#modes">A Multiple Mode Example also illustrating Simple Parameters</a>
+<li><a href="#communicating">A Weakly Isolated Task Graph (Communicating Parameters)</a>
+<li><a href="#types">An Example for Experimenting with allowed Data Types</a>
+<li><a href="#highfreq">The High Frequency Reader Example from the LCTES 2008 Paper</a>
+</ul>
+<li><a href="#application">Notes for Application Programmers</a>
+<ul>
+<li><a href="#simReal">Simulated and real-time execution modes</a>
+<ul>
+<li><a href="#obtainingJ9Bridge">Obtaining the Runtime to use with IBM WebSphere Real Time</a>
+<li><a href="#obtainingWRT">Obtaining the IBM WebSphere Real Time VM Itself</a>
+<li><a href="#testingRuntime">Testing and Using the Real-Time Runtime</a>
+</ul>
+<li><a href="#templates">Constructing Templates</a>
+<li><a href="#tasks">Writing Flexotasks</a>
+</ul>
+</ul>
+
+<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.
+
+<p>Choose <b>File→New→Project</b>. Under the
+<b>Flexotask</b> category, select <b>Flexotask Function Test and
+Samples Project</b>. If these options do not appear on the <b>New
+Project</b> wizard page, your installation did not work. Submit a <a
+href="http://sourceforge.net/tracker/?atid=1119822&group_id=242572">support
+request</a> for help.
+
+<p>You should see a Java project creation wizard page with the project
+name <b>flexotask-functiontest</b> filled in. You may change the
+location or name, although we recommend keeping the name. Press
+<b>Finish</b>.
+
+<p>If the resulting project is not created or built successfully,
+there may be a problem with your installation.
+Submit a <a
+href="http://sourceforge.net/tracker/?atid=1119822&group_id=242572">support
+request</a> for help.
+
+<p>Right click on the new project and select <b>Run As→JUnit
+Test</b>. Ignore what shows in the <b>Console</b> view but make sure
+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>
+
+<p>The Flexible Task Graph systems is described in a paper in LCTES
+2008, and the four programming models that it consolidates are each
+described in an earlier paper. Here are links to all five papers.
+
+<ul>
+<li><a href="http://portal.acm.org/citation.cfm?id=1375659">Flexible
+task graphs: a unified restricted thread programming model for
+java</a> by Joshua Auerbach, David F. Bacon, Rachid Guerraoui, Jesper
+Honig Spring, and Jan Vitek, published in LCTES 2008.
+<li><a
+href="http://portal.acm.org/citation.cfm?id=1133255.1134015">Eventrons:
+a Safe Programming Construct for High-frequency Hard Real-time
+Applications</a> by D. Spoonhower, J. Auerbach, D. F. Bacon, P.
+Cheng, and D. Grove, published in PLDI 2006.
+<li><a href="http://portal.acm.org/citation.cfm?id=1254775">Java Takes
+Flight: Time-portable Real-time Programming with Exotasks</a> by
+J.Auerbach, D. F. Bacon, D. T. Iercan, C. M. Kirsch, V. T. Rajan,
+H. R. Roeck, and R. Trummer, published in LCTES 2007
+<li><a href="http://portal.acm.org/citation.cfm?id=1254837">Reflexes:
+abstractions for highly responsive systems</a> by J. Spring, F. Pizlo,
+R. Guerraoui, and J. Vitek, published in VEE 2007.
+<li><a href="http://portal.acm.org/citation.cfm?id=1297043">Streamflex:
+high-throughput stream programming in java</a> by J. Spring, J. Privat,
+R. Guerraoui, J. Vitek, published in OOPSLA 2007
+</ul>
+
+<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
+structured as a set of individual sample programs that can be
+inspected for guidance on how to get started. Each sample program
+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
+LCTES 2007 Exotasks Paper</h3>
+
+<p>The package for this example is called <b>lctes2007</b> The example
+does not do anything very exciting but it allows you to do the
+following.
+
+<ol>
+<li>Inspect the Flexotask Template using the Flexotask editor. Double
+click on the file <b>Example.ftg</b> in the package folder.
+
+<li>Look at the code of each Flexotask by double clicking on it the editor.
+
+<li>Look at the main program code to run the task graph. Note the use
+of the <b>Generator</b> class which is discussed below.
+</ol>
+
+<p>One of the source files in this example (<b>Generator.java</b>) is
+machine-generated. The main program obtains the Flexotask template
+corresponding to <b>Example.ftg</b> by executing
+<b>Generator.generateGraph()</b>. This is only one of several ways to
+obtain the template at runtime but it combines the advantages of (1)
+working on embedded systems that don't have an XML parser and (2)
+using the <b>Example.ftg</b> file created by the graphical editor
+instead of a programmatic API to obtain the template.
+
+<p>Take a look at the file <b>generators.xml</b>. You will see something like
+this:
+
+<pre>
+<java classname="com.ibm.realtime.flexotask.tools.FlexotaskXMLParser"
+ dir="${basedir}/src/lctes2007/" fork="yes">
+ <classpath>
+ <pathelement path="${flexotask.library}"/>
+ </classpath>
+ <arg value="Example.ftg"/>
+ <arg value="Generator"/>
+ <arg value="lctes2007"/>
+</java>
+</pre>
+
+<p>The program <b>FlexotaskXMLParser.main()</b> will convert a
+Flexotask template into a "generator class" for use at runtime.
+Details on the syntax are in <a
+href="com/ibm/realtime/flexotask/tools/FlexotaskXMLParser.html#main(java.lang.String[])">the
+javadoc</a>. The special <b>Ant</b> property <b>flexotask.library</b>
+will make this program available in a build script.
+
+<p>The <b>lctes2007</b> example illustrates a current limitation of the Flexotask
+editor (but not of the programming model). If you open
+<b>Example.ftg</b> in the editor and click on the first connection,
+you will note that the connection data type is <b>double[]</b> (as in
+the paper). The code of <b>Sensor</b> and <b>Compute</b> indeed
+assumes this, and the example executes correctly. However, if you had
+tried to enter this example from scratch, you would find that the
+<b>Class selection</b> dialog (based on the standard Eclipse <b>Open
+Type</b> dialog) does not permit the specification of array classes.
+To specify array classes in a template, simply bypass the editor. In
+the editor, enter an arbitrary class such as <b>Object</b>. Then,
+edit the resulting <b>Example.ftg</b> file with a text editor, change
+<b>java.lang.Object</b> to <b>double[]</b>. Then, return to the
+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
+Simple Parameters</h3>
+
+<p>The <b>modes</b> example illustrates the more advanced of the two
+supplied timing grammars. When you examine <b>modes/Example.ftg</b>
+in the Flexotask editor, you will see that it employs the <b>TT
+Multi-Mode</b> grammar, which permits the program to be divided into
+<i>modes</i>. A mode is simply a subset of the graph that is active
+at a particular time; by switching modes, the program can change which
+subset is active. A Flexotask can belong to multiple modes. For
+example, while <b>downTask</b> belongs only to the <b>countDown</b>
+mode and <b>upTask</b> belongs only the <b>countUp</b> mode, the
+<b>counter</b> task belongs to both. As illustrated, different modes
+can have different periods, and a task can have different timing
+offsets in the different modes to which it belongs.
+
+<p>This example also shows the two special task types available in the
+model, <i>communicators</i> and <i>predicates</i> (which were called
+<i>conditions</i> in the LCTES 2007 Exotasks paper). A predicate
+controls the switching from one mode to another, based on the value
+returned by its <b>isTrue</b> method and its <b>targetMode</b>
+property. A communicator is just a typed buffer that holds a value
+between periods. Communicators also have a special role to play in
+writing distributers and may be special to certain timing grammars
+(the HTL timing grammar used for Exotasks gave a special role to
+communicators; this grammar has not yet been converted to work with
+the Flexotask model but may be available soon).
+
+<p>Finally, the example illustrates one useful role for parameters.
+This example is strongly isolated, so the parameters passed to the two
+predicates are passed "by value" (ie, they are cloned) and cannot be
+used to communicate with other Java threads. But, they are used in a
+more traditional sense to parameterize the behavior of the predicates.
+Both predicates share the same implementation (the <b>Equals</b>
+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
+(Communicating Parameters)</h3>
+
+<p>The <b>communicating</b> example is an example of how a Flexible
+Task Graph can use pinned reference-immutable objects and the exchange
+of scalar values with the rest of the Java application. In this
+example, the tasks <b>T1, T2,</b> and <b>T3</b> are strongly isolated
+while <b>Input</b> and <b>Output</b> are weakly isolated. The
+implementation Flexotask classes of the two "edge" tasks
+(<b>InputHandler</b> and <b>OutputHandler</b>, respectively), use the
+simplest possible example of a reference-immutable object (an
+<b>int[]</b> of length 1) to pass integer values to and from the
+outside. As a result, this example is able to pass values into the
+graph for processing and get "answers" out the other end.
+
+<p>This example also differs from the previous two in that it does not
+use a <b>Generator</b> class but instead relies on directly parsing the XML
+in <b>Example.ftg</b>. In the main program you will see the following.
+
+<pre>
+InputStream in = Main.class.getResourceAsStream("Example.ftg");
+FlexotaskTemplate spec = FlexotaskXMLParser.parseStream(in);
+</pre>
+
+This is one of several ways to use the <a
+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>
+
+<p>The <b>types</b> example illustrates that both <b>ArrayList</b> and
+<b>HashMap</b> are acceptable types to be passed between Flexotasks
+(and used within them). It also provides a starting point for
+experimenting with more types (see the <b>switch</b> statements in
+both <b>DataSource</b> and <b>DataSink</b>). Note that the type of
+the connection between the two tasks is <b>java.lang.Object</b> which
+permits any type legal for use within an Flexible Task Graph to be
+transmitted between the two Flexotasks.
+
+<p>This example also illustrates that a <a
+href="com/ibm/realtime/flexotask/template/FlexotaskTemplate.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>
+
+<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
+published in LCTES 2008. Like the <b>types</b> example, the
+<b>Main</b> class in this example constructs its
+<b>FlexotaskTemplate</b> programmatically.
+
+<p>A number of flexotask features are shown.
+
+<ul>
+<li>The Flexotask in this example (<b>HighFreqReader</b>) extends
+<b>AtomicFlexotask</b> and implements <b>HighFreqReaderIntf</b>, which
+extends <b>ExternalMethods</b>. Thus, this Flexotask follows the
+design pattern for atomic Flexotasks as discussed in Section 2.3.2 of
+the paper.
+
+<li>The template created in the main program uses the <em>manual</em>
+approach to establishing the stable and transient classes (see Section
+2.2 of the paper). The classes specifically added to the template are
+stable and others are transient.
+
+<li>The main program also illustrates the use of the <a
+href="com/ibm/realtime/flexotask/tracing/package-summary.html">tracing
+support</a> provided with the Flexible Task Graphs system.
+
+<li>To aid in evaluating the performance of this (and other) Flexotask
+applications, we provide a copy of the <b>MemoryAllocator</b> class
+which simulates the effect of an allocation-intensive application
+running in the same virtual machine with the task graph.
+</ul>
+
+<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>
+
+<p>When you test a Flexotask program under Eclipse, you are running in
+"simulated" mode. That is,
+<ul>
+<li>the task graph is being run by ordinary
+threads that have no special rights and are paused by the garbage collector
+
+<li>the "private memory areas" of the Flexotasks are fictional and
+everything is, in fact, allocated on the public heap
+
+<li>scheduling is not real-time
+</ul>
+
+Simulated execution gives you a opportunity to find non-time-related
+errors and to check that your code is "valid" in Flexotask terms (does
+not violate any of the Flexotask restrictions). But, eventually, you
+will want to run your program in real-time mode, which must take place
+under an OS with real-time capabilities and using a Java VM that
+supports the Flexotask real-time VM interfaces.
+
+<p>Currently, the only real-time platform for which full support
+exists is RT Linux with the IBM WebSphere Real Time VM (WRT). Other
+platforms could be supported in the future if other VM vendors (or
+open source VM projects) choose to implement the <a
+href="com/ibm/realtime/flexotask/vm/FlexotaskVMBridge.html">FlexotaskVMBridge</a>
+interface. If you installed Flexible Task Graphs starting from the
+instructions on IBM alphaWorks, you will have the necessary software
+for running on WRT. Otherwise you will need to obtain the IBM runtime
+for that platform as described <a
+href="#obtainingJ9Bridge">below</a>.
+
+<p>Although you <em>can</em> configure Eclipse to run on the same
+platform as the real-time VM, we generally assume that you will switch
+to a "batch" mode of execution for this later phase of testing. The
+Flexotask development system provides a wizard that will generate a
+runtime for you to run in the real-time environment. If you are not
+actively developing or extending the Flexotask system (if you are just
+doing application programming) you should only have to do this runtime
+generation step once, after which you just use the resulting runtime
+for all of your real-time execution.
+
+<p>Select <b>File→Export→Flexotask→Flexotask
+Runtime</b>. You may get something like this:
+<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
+href="#obtainingJ9Bridge">the next subsection</a>.
+
+<p>If you do have the necessary IBM support, you will get something
+more like this:
+
+<p><img width=472 height=550 src="runtimeExportDialog.jpg"></p>
+
+<p>Select a destination archive (zip) file or directory. If you have
+remotely mounted a file system from your target real-time platform,
+you can export directly into this file system. However, if you are
+running Eclipse on windows and the target platform is Unix
+(e.g. Linux), the file permissions may come out wrong when exporting
+to a directory. You can avoid this problem by exporting to an archive
+file and then unzipping it on the target platform (or you can fix the
+permissions manually using <b>chmod</b> on the target platform).
+
+<p>The generated runtime is only useful in conjunction with a licensed
+copy of WRT running on a real-time Linux kernel. For more information
+see <a href="#obtainingWRT">below</a>.
+
+<p>The generated runtime can be tested using the procedure described
+<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
+Use with IBM WebSphere Real Time</h4>
+
+<p>This procedure is only necessary if you installed Flexible Task
+Graphs exclusively from the open-source update site on SourceForge.
+If you used the installation procedure supplied by IBM alphaWorks you
+will already have this support.
+
+<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>
+
+<p><p>Select <b>Help→Software Updates→Find And
+Install</b>, then select <b>Search For New Features to Install</b> and
+click <b>Next</b>. You should see an update site labeled <b>IBM
+Flexible Task Graphs Runtime Update Site</b>. Select (only) that site
+and click <b>Finish</b>. <p>Drill down to the feature labelled
+<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>
+
+<p><p>Select <b>Help→Software Updates</b>, then select the
+<b>Available Software</b> tab. If you don't see the update site
+labelled <b>IBM Flexible Task Graphs Runtime Update Site</b>, click on
+<b>Manage Sites</b> and then add a checkmark to the needed site to
+make it visible. Click <b>Ok</b> and the site should now be visible
+in the main dialog. <p>Drill down to the feature labelled
+<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>
+
+<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
+DeveloperWorks</a>. You will need to establish an IBM id, answer some
+survey questions, and adhere to the terms of the license. As of this
+writing there are two versions available: Version 1 (SR3) implements
+the Java 5 language. Version 2 implements the Java 6 language. If
+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.
+
+<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.
+
+<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
+Enterprise MRG V1 (2.6.24.7-74.el5rt) and with SUSE Linux Enterprise
+Real Time 10 (2.6.22.19-0.12-rt). However, other recent Linux kernels
+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>
+
+<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
+<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.
+
+<p>The following instructions apply whenever you are running
+Flexotasks in real-time mode.
+
+<ul>
+<li>Set the environment variable <b>WRT_HOME</b> to the full path of the directory created by
+installing WRT.
+
+<li>Set the environment variable <b>FTG_HOME</b> to the full path of the directory containing
+the Flexotask runtime (this is either the directory you exported to or the directory created
+by unzipping the archive you exported to).
+</ul>
+
+<p>To run the function test (assuming that
+<b>flexotaskFunctionTest.jar</b> resides in the local directory):
+
+<pre>
+$FTG_HOME/bin/ejava -jar flexotaskFunctionTest.jar
+</pre>
+
+That is, the <b>ejava</b> (or <b>ejavaw</b>) launchers substitute for
+the normal <b>java</b> and <b>javaw</b> launchers and have the same
+syntax. They automatically add the necessary libraries and natives to
+the various paths used by WRT and invoke WRT to run your Flexotask
+program.
+
+<p>This example should be readily extended to running your own
+programs.
+
+<h3><a name="templates"></a>Constructing Templates</h3>
+
+<h3><a name="tasks"></a>Writing Flexotasks</h3>
+
</body>
</html>
Added: trunk/flexotask/doc/runtimeExportDialog.jpg
===================================================================
(Binary files differ)
Property changes on: trunk/flexotask/doc/runtimeExportDialog.jpg
___________________________________________________________________
Added: svn:mime-type
+ image/jpeg
Added: trunk/flexotask/doc/runtimeExportError.jpg
===================================================================
(Binary files differ)
Property changes on: trunk/flexotask/doc/runtimeExportError.jpg
___________________________________________________________________
Added: svn:mime-type
+ image/jpeg
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
