Menu
▾
▴
[flexotask-commits] SF.net SVN: flexotask:[94] trunk/flexotask/doc
|
From: <jsa...@us...> - 2008-11-12 21:43:27
|
Revision: 94
http://flexotask.svn.sourceforge.net/flexotask/?rev=94&view=rev
Author: jsauerbach
Date: 2008-11-12 21:43:22 +0000 (Wed, 12 Nov 2008)
Log Message:
-----------
Further progress on documentation.
Modified Paths:
--------------
trunk/flexotask/doc/flexotaskProgramming.html
Added Paths:
-----------
trunk/flexotask/doc/initialProperties.jpg
Modified: trunk/flexotask/doc/flexotaskProgramming.html
===================================================================
--- trunk/flexotask/doc/flexotaskProgramming.html 2008-11-12 19:40:34 UTC (rev 93)
+++ trunk/flexotask/doc/flexotaskProgramming.html 2008-11-12 21:43:22 UTC (rev 94)
@@ -17,7 +17,7 @@
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
+development </em> (creating new tools to generate Flexible Task
Graph templates).
<p>The following outline will help you find relevant information.
@@ -34,6 +34,7 @@
</ul>
<li><a href="#application">Notes for Application Programmers</a>
<ul>
+<li><a href="#creating"></a>Creating and Converting Flexotask Projects</a>
<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>
@@ -43,12 +44,13 @@
<li><a href="#templates">Constructing Templates</a>
<ul>
<li><a href="#templateAPI">The Template API</a>
+<li><a href="#editor">The Flexotask Editor</a>
</ul>
<li><a href="#tasks">Writing Flexotasks</a>
</ul>
</ul>
-<br><hr><br><h2><a name="post-install"></a>Post-Install Testing</h2>
+<br><hr><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.
@@ -76,7 +78,7 @@
that the <b>JUnit</b> view eventually shows (after about a minute)
that all tests ran successfully.
-<br><hr><br><h2><a name="papers"></a>Relevant papers</h2>
+<br><hr><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
@@ -104,7 +106,7 @@
R. Guerraoui, J. Vitek, published in OOPSLA 2007
</ul>
-<br><hr><br><h2><a name="samples"></a>The Samples</h2>
+<br><hr><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
@@ -113,7 +115,7 @@
occupies a package. The procedure for creating this project is
described under <a href="#post-install">post-install testing</a>.
-<br><hr><br><h3><a name="pendulum"></a>The Inverted Pendulum example from the
+<br><hr><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
@@ -177,7 +179,7 @@
Flexotask editor to complete the example. This limitation may be
removed soon if someone wants to work on eliminating it.
-<br><hr><br><h3><a name="modes"></a>A Multiple Mode Example also illustrating
+<br><hr><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
@@ -214,7 +216,7 @@
class) but they use the parameter as an <b>Integer</b> comparand to
cause the two predicates to perform different tests.
-<br><hr><br><h3><a name="communicating"></a>A Weakly Isolated Task Graph
+<br><hr><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
@@ -242,7 +244,7 @@
href="com/ibm/realtime/flexotask/tools/FlexotaskXMLParser.html">FlexotaskXMLParser</a>
class programmatically.
-<br><hr><br><h3><a name="types"></a>An Example for Experimenting with allowed Data Types</h3>
+<br><hr><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
@@ -260,7 +262,7 @@
<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.
-<br><hr><br><h3><a name="highfreq"></a>The High Frequency Reader Example from the LCTES 2008 Paper</h3>
+<br><hr><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
@@ -292,13 +294,90 @@
running in the same virtual machine with the task graph.
</ul>
-<br><hr><br><h2><a name="application"></a>Notes for Application Programmers</h2>
+<br><hr><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.
-<br><hr><br><h3><a name="simReal"></a>Simulated and real-time execution modes</h3>
+<br><hr><h3><a name="creating"></a>Creating and Converting Flexotask Projects</h3>
+<p>Flexotask development requires Eclipse projects that are configured
+with a special builder, a special classpath container, and an extra
+binary folder. Immediately after installation you should have created
+an example project (<b>flexotask-functiontest</b>) which has these
+characteristics, but that project was created as a special case by the
+Flexotask development-time support. This section deals with the more
+general task of creating Flexotask-enabled projects for doing your own
+work.
+
+<p>To make a simple Java project (not a PDE project) that is
+Flexotask-enabled, choose <b>File→New→Project</b>. Under
+the <b>Flexotask</b> category, select <b>Flexotask Project</b>. The
+rest of the project creation dialog is exactly like creating any Java
+project. The resulting project will have these special
+characteristics.
+
+<ol>
+<li>You will see a <b>Flexotask Libraries</b> entry immediately under
+your <b>JRE System Library</b> entry in the Package Explorer's view of
+the project (you might not see this if you have <b>Libraries from
+External</b> filtered out of your Package Explorer view). If you open
+the <b>Flexotask Libraries</b> entry you will see that it contains (at
+least) <b>flexotask.jar</b>, <b>realtimeAnalysis.jar</b>, and
+<b>bcel-5.2.jar</b>. If the project is at the 1.5 language compliance
+level or higher, then you will also see an entry for
+<b>flexotaskGeneric.jar</b>. This provides versions of some API
+classes that support Java generics. In order to support running on
+older VMs for some embedded systems, the Flexotask development
+environment will work when the language compliance level is set below
+1.5 and will generate code for older VMs. In that case, the
+<b>flexotaskGeneric.jar</b> is omitted and you will not be able to use
+Java generics in conjunction with the Flexotask API. As far as the
+Flexotask support is concerned, you can change the compliance level at
+any time.
+
+<li>You will see an extra folder <b>generated</b> which will remain
+empty unless and until you write one or more classes that inherit from
+<a
+href="com/ibm/realtime/flexotask/AtomicFlexotask.html">AtomicFlexotask</a>.
+If the <b>generated</b> folder becomes non-empty, you will need to
+bear this in mind when exporting a <b>jar</b> file from your project
+to run on another machine. Classes from the <b>generated</b> binary
+folder must take precedence over classes in the normal <b>bin</b>
+folder. One way to build a correct jar file is shown in the Ant
+script <b>export.xml</b> in the <b>flexotask-functiontest</b> project.
+
+<li>The project has an additional builder that will check your
+Flexotasks for correctness during development and will rewrite any
+<b>AtomicFlexotask</b> classes into the <b>generated</b> directory.
+At present, this builder writes to the console, so you may have noticed
+its presence when it issued messages like the following:
+<pre>
+Running Flexotask Builder ...
+
+No Flexotasks found in project.
+
+Completed checking of Flexotask code in 0.0 seconds.
+Validation time: 0 Rewriting time: 0
+</pre>
+</ol>
+
+<p>Once you have a Flexotask project, you can add PDE support, if
+needed, by right-clicking on the project in the Package Explorer then
+selecting <b>PDE Tools→Convert Projects to Plugin Projects</b>.
+
+<p>You can also add Flexotask support to any non-Flexotask Java
+project (including a PDE project) by right-clicking on the project in
+the Package Explorer then selecting <b>Convert to Flexotask
+Project</b>.
+
+<p>The Flexotask Graphical Editor is meant to be used in conjunction
+with Flexotask-enabled projects but technically it becomes bound to
+any file with the suffix <b>.ftg</b> whether that file is in a
+Flexotask project or not.
+
+<br><hr><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>
@@ -370,7 +449,7 @@
<a href="#testingRuntime">below</a> which also provides general
information about running programs in the real-time execution mode.
-<br><hr><br><h4><a name="obtainingJ9Bridge"></a>Obtaining the Runtime to
+<br><hr><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
@@ -381,7 +460,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.
-<br><hr><br><h5>Obtaining the IBM Runtime using Eclipse 3.3.x</h5>
+<br><hr><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
@@ -391,7 +470,7 @@
<b>Flexible Task Graphs Runtime for IBM WebSphere Real Time</b> and
select it. Complete the dialog to install the feature.
-<br><hr><br><h5>Obtaining the IBM Runtime using Eclipse 3.4.x</h5>
+<br><hr><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
@@ -402,7 +481,7 @@
<b>Flexible Task Graphs Runtime for IBM WebSphere Real Time</b> and
select it. Complete the dialog to install the feature.
-<br><hr><br><h4><a name="obtainingWRT"></a>Obtaining The IBM WebSphere Real Time VM Itself</h4>
+<br><hr><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
@@ -428,7 +507,7 @@
will work if they have the real-time capabilities (the suffix -rt
indicates this).
-<br><hr><br><h4><a name="testingRuntime"></a>Testing and Using the Real-Time Runtime</h4>
+<br><hr><h4><a name="testingRuntime"></a>Testing and Using the Real-Time Runtime</h4>
<p>The <b>flexotask-functiontest</b> project provides a script for
packaging itself as a <b>jar</b> file so that you can repeat the same
@@ -467,7 +546,7 @@
<p>This example should be readily extended to running your own
programs.
-<br><hr><br><h3><a name="templates"></a>Constructing Templates</h3>
+<br><hr><h3><a name="templates"></a>Constructing Templates</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
@@ -514,7 +593,7 @@
the target system has an XML parser.
</ol>
-<br><hr><br><h4><a name="templateAPI"></a>The Template API</h4>
+<br><hr><h4><a name="templateAPI"></a>The Template API</h4>
<p>For fast reference to subsections, use this outline.
<ul>
@@ -524,21 +603,25 @@
<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>
+<li><a href="#templateStable">Adding Stable Classes to the 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,
+properties, tasks, connections, and stable classes. Tasks include normal tasks,
predicates, and communicators.
-<br><hr><br><h5><a name="templateGlobal"></a>Template Global Properties</h5>
+<br><hr><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>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). This property, and the related list of stable classes in the
+template, is discussed <a href="#templateStable">later</a>.
<li><b>setSynchronizing</b> to establish whether tasks of the graph
are allowed to use Java synchronized methods and blocks (default is
@@ -584,7 +667,7 @@
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>
+<br><hr><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.
@@ -652,7 +735,7 @@
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>
+<br><hr><h5><a name="templatePorts"></a>Adding Ports to a Task</h5>
<p>The least error-prone way to specify ports programmatically is as follows.
@@ -681,7 +764,7 @@
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>
+<br><hr><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>
@@ -705,7 +788,7 @@
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>
+<br><hr><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>
@@ -727,7 +810,7 @@
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>
+<br><hr><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>
@@ -775,7 +858,82 @@
basis as tasks.
</ul>
-<br><hr><br><h3><a name="tasks"></a>Writing Flexotasks</h3>
+<br><hr><h5><a name="templateStable"></a>Adding Stable Classes to the Template</h5>
+<p>In the Flexible Task Graphs model, newly allocated objects are
+assigned to stable or transient storage within the Flexotask private
+memory area based on their classes (see Section 2.2 of the LCTES 2008
+paper). This assignment is done either implicitly or explicitly, and
+there are both two different implicit mechanisms and two different
+explicit mechanisms.
+
+<p>Note that if you do not call the <a
+href="com/ibm/realtime/flexotask/template/FlexotaskTemplate.html#setStableMode(com.ibm.realtime.flexotask.template.FlexotaskStableMode)">setStableMode</a>
+function on the template or if you set the stable mode to <a
+href="com/ibm/realtime/flexotask/template/FlexotaskStableMode.html#DEFAULT">FlexotaskStableMode.DEFAULT</a>,
+then all classes are implicitly stable. This means that you are
+relying on scheduled garbage collection of the Flexotask private heaps
+to ensure that you don't run out of memory (or else your Flexotasks
+don't allocate anything). When there is a reasonable amount of slack
+in your real-time schedule, this works fine (as in the Exotask model).
+But, when there is little slack, the scheduled garbage collections
+might not be able to keep up unless you also take steps to limit the
+stable allocation rate by choosing one of the other options.
+
+<p>If you set the stable mode to <a
+href="com/ibm/realtime/flexotask/template/FlexotaskStableMode.html#INFER">FlexotaskStableMode.INFER</a>,
+then the system will infer the smallest safe set of stable classes and
+mark other classes as transient. While this result is sometimes
+optimal and often good, it has the disadvantage of hiding what is
+going on. It is difficult to know exactly what the storage
+utilization of your program really is and whether you will therefore
+run out of resources on some pathological execution.
+
+<p>The remaining two options are <em>explicit</em> in that you declare
+exactly what classes you intend to be stable. For Flexotask programs
+that are written largely from scratch we provide <a
+href="com/ibm/realtime/flexotask/template/FlexotaskStableMode.html#MARKER">FlexotaskStableMode.MARKER</a>,
+which requires that all stable classes must (directly or indirectly)
+implement the marker interface <a
+href="com/ibm/realtime/flexotask/Stable.html">Stable</a>. The
+validator will then check that no stable class has transient data
+members.
+
+<p>For Flexotask programs that use existing classes, where those
+classes must be designated as stable but you do not wish to make all
+classes stable, we permit the stable classes to be listed explicitly
+in the template. Set the stable mode to <a
+href="com/ibm/realtime/flexotask/template/FlexotaskStableMode.html#MANUAL">FlexotaskStableMode.MANUAL</a>.
+Then, add the names of all stable classes to the <b>Set</b> obtained
+by calling <a
+href="com/ibm/realtime/flexotask/template/FlexotaskTemplate.html#getStableClasses()">getStableClasses()</a>
+on the template. In a Java 1.5 (or later) project,
+<b>getStableClasses()</b> returns a <b>Set<String></b> instead
+of a raw <b>Set</b>.
+
+<br><hr><h4><a name="editor"></a>The Flexotask Editor</h4>
+
+<p>To use the Flexotask Editor, just create a file with the extension
+<b>.ftg</b> (for example, using <b>File→New→File</b>).
+The editor become the default editor for that file and will help you
+create an XML-format Flexotask template stored in that file. In
+choosing the folder to contain the <b>.ftg</b> file, bear in mind your
+intended use. If you plan to parse the file directly using the <a
+href="com/ibm/realtime/flexotask/tools/FlexotaskXMLParser.html#parseStream(java.io.InputStream)">parseStream</a> method of <b>FlexotaskXMLParser</b>, it is
+useful to put it in the same package folder as the class that will use
+it (examples of this design pattern can be found in
+<b>communicating.Main</b> in the <b>flexotask-functiontest</b>
+project).
+
+<p>When the editor first comes up has a blank canvas, a gear-like icon
+on the tab, and a flyout palette at the upper right. A Properties
+view is created if you don't already have one, and it is unburied if
+you do have one. You use this Properties view to augment information
+in the editor's graphical view. The initial properties view will look
+something like this.
+<p><img width=377 height=134 src="initialProperties.jpg"/>
+
+<br><hr><h3><a name="tasks"></a>Writing Flexotasks</h3>
+
</body>
</html>
Added: trunk/flexotask/doc/initialProperties.jpg
===================================================================
(Binary files differ)
Property changes on: trunk/flexotask/doc/initialProperties.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.
|
