Menu
▾
▴
[flexotask-commits] SF.net SVN: flexotask:[101] trunk/flexotask/doc
|
From: <jsa...@us...> - 2008-11-14 17:12:19
|
Revision: 101
http://flexotask.svn.sourceforge.net/flexotask/?rev=101&view=rev
Author: jsauerbach
Date: 2008-11-14 17:12:16 +0000 (Fri, 14 Nov 2008)
Log Message:
-----------
Finish editor section of the document. The document is now deemed good enough to support the public release on Nov 18 and focus will shift to the public web page and wiki. Of course the document needs a lot more work.
Modified Paths:
--------------
trunk/flexotask/doc/flexotaskProgramming.html
trunk/flexotask/doc/palette.jpg
Added Paths:
-----------
trunk/flexotask/doc/changingPorts.jpg
trunk/flexotask/doc/communicatorProperties.jpg
Added: trunk/flexotask/doc/changingPorts.jpg
===================================================================
(Binary files differ)
Property changes on: trunk/flexotask/doc/changingPorts.jpg
___________________________________________________________________
Added: svn:mime-type
+ image/jpeg
Added: trunk/flexotask/doc/communicatorProperties.jpg
===================================================================
(Binary files differ)
Property changes on: trunk/flexotask/doc/communicatorProperties.jpg
___________________________________________________________________
Added: svn:mime-type
+ image/jpeg
Modified: trunk/flexotask/doc/flexotaskProgramming.html
===================================================================
--- trunk/flexotask/doc/flexotaskProgramming.html 2008-11-14 15:32:01 UTC (rev 100)
+++ trunk/flexotask/doc/flexotaskProgramming.html 2008-11-14 17:12:16 UTC (rev 101)
@@ -24,6 +24,8 @@
<ul>
<li><a href="#post-install">Post-Install Testing</a>
<li><a href="#papers">Relevant Papers</a>
+<li><a href="#application">Notes for Application Programmers</a>
+<ul>
<li><a href="#samples">The Samples</a>
<ul>
<li><a href="#pendulum">The Inverted Pendulum Example from the LCTES 2007 Exotasks Paper</a>
@@ -32,8 +34,6 @@
<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="#creating">Creating and Converting Flexotask Projects</a>
<li><a href="#simReal">Simulated and real-time execution modes</a>
<ul>
@@ -47,7 +47,14 @@
<li><a href="#editor">The Flexotask Editor</a>
</ul>
<li><a href="#tasks">Writing Flexotasks</a>
+<li><a href="#validation">Validating and Instantiating Flexible Task Graphs</a>
+<li><a href="#wcet">Specifying WCET and WCA information</a>
+<li><a href="#cloning">Deep cloning at test time</a>
+<li><a href="#tracing">Using the Tracing Support</a>
</ul>
+<li><a href="#extender">Notes for Flexotask System Extenders</a>
+<li><a href="#developer">Notes for Flexotask Core Developers</a>
+<li><a href="#toolWriter">Notes for Flexotask Tool Developers</a>
</ul>
<br><hr><h2><a name="post-install"></a>Post-Install Testing</h2>
@@ -106,8 +113,10 @@
R. Guerraoui, J. Vitek, published in OOPSLA 2007
</ul>
-<br><hr><h2><a name="samples"></a>The Samples</h2>
+<br><hr><h2><a name="application"></a>Notes for Application Programmers</h2>
+<br><hr><h3><a name="samples"></a>The Samples</h3>
+
<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
@@ -115,8 +124,8 @@
occupies a package. The procedure for creating this project is
described under <a href="#post-install">post-install testing</a>.
-<br><hr><h3><a name="pendulum"></a>The Inverted Pendulum example from the
-LCTES 2007 Exotasks Paper</h3>
+<br><hr><h4><a name="pendulum"></a>The Inverted Pendulum example from the
+LCTES 2007 Exotasks Paper</h4>
<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
@@ -179,8 +188,8 @@
Flexotask editor to complete the example. This limitation may be
removed soon if someone wants to work on eliminating it.
-<br><hr><h3><a name="modes"></a>A Multiple Mode Example also illustrating
-Simple Parameters</h3>
+<br><hr><h4><a name="modes"></a>A Multiple Mode Example also illustrating
+Simple Parameters</h4>
<p>The <b>modes</b> example illustrates the more advanced of the two
supplied timing grammars. When you examine <b>modes/Example.ftg</b>
@@ -216,8 +225,8 @@
class) but they use the parameter as an <b>Integer</b> comparand to
cause the two predicates to perform different tests.
-<br><hr><h3><a name="communicating"></a>A Weakly Isolated Task Graph
-(Communicating Parameters)</h3>
+<br><hr><h4><a name="communicating"></a>A Weakly Isolated Task Graph
+(Communicating Parameters)</h4>
<p>The <b>communicating</b> example is an example of how a Flexible
Task Graph can use pinned reference-immutable objects and the exchange
@@ -244,7 +253,7 @@
href="com/ibm/realtime/flexotask/tools/FlexotaskXMLParser.html">FlexotaskXMLParser</a>
class programmatically.
-<br><hr><h3><a name="types"></a>An Example for Experimenting with allowed Data Types</h3>
+<br><hr><h4><a name="types"></a>An Example for Experimenting with allowed Data Types</h4>
<p>The <b>types</b> example illustrates that both <b>ArrayList</b> and
<b>HashMap</b> are acceptable types to be passed between Flexotasks
@@ -262,7 +271,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><h3><a name="highfreq"></a>The High Frequency Reader Example from the LCTES 2008 Paper</h3>
+<br><hr><h4><a name="highfreq"></a>The High Frequency Reader Example from the LCTES 2008 Paper</h4>
<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
@@ -294,8 +303,6 @@
running in the same virtual machine with the task graph.
</ul>
-<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.
@@ -959,6 +966,7 @@
<li><a href="#editorGlobal">Specifying Global Properties</a>
<li><a href="#editorGlobalTiming">Specifying Global Timing Properties</a>
<li><a href="#editorTask">Specifying Task Properties</a>
+<li><a href="#editorCommunicator">Specifying Communicator Properties</a>
<li><a href="#editorConnection">Specifying Connection Properties</a>
<li><a href="#editorPort">Specifying Ports and their Properties</a>
</ul>
@@ -968,7 +976,11 @@
<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.
+create an XML-format Flexotask template stored in that file. If you
+prefer, there is also a creation wizard
+(<b>File→New→Other</b>), then open the <b>Flexotask</b>
+category and select <b>Flexotask Graph</b>). Either way, you end up
+in the same editor.
<p>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
@@ -986,10 +998,10 @@
3.4 the palette control looks like this.
<p><img width=229 height=129 src="paletteControl.jpg"/>
-g
+
<p>Clicking on the control reveals the palette, which looks like this.
-<p><img width=150 height=283 src="palette.jpg"/>
+<p><img width=140 height=305 src="palette.jpg"/>
<p>The palette will also fly out temporarily when you simply place the
mouse cursor on the control. In any case, the palette can be
@@ -1030,6 +1042,33 @@
<p><img width=401 height=265 src="simpleGraph.jpg"/>
+<p>In creating connections, bear three things in mind.
+
+<ol>
+<li>Connections are directional. Start by clicking on the intended
+source task, then move to the target and click there. Because of the
+way connections are drawn it is useful to organize the graph so that
+the majority of connections go from left to right (of course, this may
+not be possible for all connections if the graph contains cycles). If
+your initial result is not visually satisfying, tasks may be dragged
+to new locations on the canvas without disconnecting the connections.
+
+<li>Creating connections between tasks can have the side-effect of
+creating or altering the ports of those tasks. Tasks and connections
+have explicit graphic representations while ports are implicit. The
+anchor-points of the connections on the edges of the tasks are chosen
+to make connections distinct and reduce clutter: they do <em>not</em>
+represent ports. Unless you use the <b>Properties</b> view to
+disambiguate, every task will get at most one input port and at most
+one output port. When this is not what you want, consult the
+instructions given later under <a href="#editorPort">Specifying Ports
+and their Properties</a>.
+
+<li>When the connection tool is active you can't use it to select and
+move elements on the canvas. Switch back to the select tool for that
+purpose.
+</ol>
+
<p>The tasks and connections in the editor are color coded: yellow
indicates missing required information and red indicates an error. In
a "complete" (ready to run) graph the tasks are grey and the
@@ -1048,7 +1087,7 @@
properties.
<p>Subsequent sections discuss the specifics of specifying global
-properties, global timing properties, task properties, connection properties, and ports (with
+properties, global timing properties, task properties, communicator properties, connection properties, and ports (with
their properties) using the editor.
<br><hr><h5><a name="editorGlobal"/>Specifying Global Properties</h5>
@@ -1095,7 +1134,7 @@
<p>Single-click on the timing grammar box to cause the
<b>Properties</b> view to show timing-related global properties
-specific to the timing gramamr. The property sheet for those
+specific to the timing grammar. The property sheet for those
properties will vary according to the chosen grammar. For example,
the TT Single Mode grammar has a single property, <b>Period</b>, which
is the period of the graph's execution. This can be specified in
@@ -1160,8 +1199,38 @@
<br><hr><h5><a name="editorCommunicator"/>Specifying Communicator Properties</h5>
-<p>Under construction.
+<p>The communicator properties are shown in the following illustration.
+<p><img width=248 height=103 src="communicatorProperties.jpg"/>
+
+<ul>
+<li><b>Communicator Name</b> is a name for the communicator.
+Communicators are tasks and must have a name that is unique across all
+tasks.
+
+<li><b>Data Type</b> is a required property declaring the type of data
+(Java class name) handled by the communicator. The <b>Change</b>
+button for this property brings up the familiar <b>Find Type</b>
+dialog.
+
+<li><b>Initial Value</b> is an expression following the syntax
+described in the javadoc for the <a
+href="com/ibm/realtime/flexotask/template/FlexotaskTaskTemplate.html#setParameterValue(java.lang.String)">FlexotaskTaskTemplate.setParameterValue()</a>
+method. It established the initial value placed in both the input
+port and the output port of the communicator.
+
+<li><b>Timing Offsets</b>, which appears in the screenshot, is
+specific to the particular timing grammar that we chose (the TT
+Single-Mode grammar). In general, each timing grammar will induce a
+particular set of timing properties in the property views for tasks
+(including communicators) and connections. In this particular case,
+you can modify the property to specify that the task should execute at
+particular time offsets within the period established by the global
+timing property. The units used for those offsets are the same used
+for the global period (ranging from seconds to nanoseconds; see <a
+href="#editorGlobalTiming">above</a>).
+</ul>
+
<br><hr><h5><a name="editorConnection"/>Specifying Connection Properties</h5>
<p>The connection properties are shown in the following illustration.
@@ -1169,9 +1238,10 @@
<p><img width=298 height=214 src="connectionProperties.jpg"/>
<p>The <b>Basics</b> section contains properties of the connection
-itself, as described just below. The <b>Input</b> and <b>Output</b>
-sections apply to the ports at either end of the connection. How
-to modify this information is covered in the next subsection.
+itself, as described just below. The <b>Connection Source</b> and
+<b>Connection Target</b> sections apply to the ports at either end of
+the connection. How to modify this information is covered in the next
+subsection.
<ul>
<li><b>Connection Name</b> establishes a name for the connection. If
@@ -1215,13 +1285,103 @@
<p>In the editor (in contrast to the template API) ports are modified
(and, in some cases, created) by using the <b>Properties</b> view on
-connections (not tasks).
+connections (not tasks). The information under <b>Connection
+Source</b> applies to the port that is the connection's source (this
+is always an output port of some task). The information under
+<b>Connection Target</b> applies to the connection's target (the input
+port of some task).
-<p>Section under construction.
+<p>As previously noted, the act of creating the first outgoing
+connection from a task creates an output port on that task and the act
+of creating the first incoming connection to a task creates an input
+port. Type information propagates from connections and communicators
+to ports and hence to other connections. You need to intervene
+manually if a task is intended to have more than input port or more
+than one output port.
+<p>The main mechanism for establishing extra ports is to change the
+name of a port by editing the <b>Source Port Name</b> or <b>Target
+Port Name</b> properties of a connection. You will get a message like the
+following.
+
+<p><img width=440 height=146 src="changingPorts.jpg"/>
+
+<p>Select the appropriate response to either create a new port or
+proceed with the renaming (if that was your intent). Due to the
+automatic propagation of type information, it is a good practice to
+establish the right relationship between connections and ports
+<em>before</em> setting the data types of the connections (which
+propagate to the ports). This is not strictly necessary, however,
+since you can correct the type information incrementally.
+
+<p>There are also <b>Source Port Buffering</b> and <b>Target Port
+Buffering</b> properties. When changing these they become combo boxes
+that can be set to either <b>true</b> or <b>false</b>. An unbuffered
+port holds exactly one value. A buffered port holds an indefinite
+number of values, stored in the memory area of the Flexotask that owns
+the port. In either case, values are moved one at a time across the
+connection.
+
<br><hr><h3><a name="tasks"></a>Writing Flexotasks</h3>
<p>Under construction.
+<br><hr><h3><a name="validation"/>Validating and Instantiating Flexible Task Graphs</h3>
+
+<p>Under construction.
+
+<br><hr><h3><a name="wcet"/>Specifying WCET and WCA information</h3>
+
+<p>Under construction.
+
+<br><hr><h3><a name="cloning"/>Deep cloning at test time</h3>
+
+<p>Under construction.
+
+<br><hr><h3><a name="tracing">Using the Tracing Support</h3>
+
+<p>Under construction
+
+<br><hr><h2><a name="extender"/>Note for Flexotask System Extenders</h2>
+
+<p>This section is still being written. It will describe the process
+for developing new timing grammars, schedulers, distributers, and
+tracing packages, all of which can be added to the Flexible Task Graph
+infrastructure in the form of Eclipse features and plugins.
+
+<p>Meanwhile, we want to support this kind of effort and the open
+source framework should allow it. Please identify yourself by sending
+an email to <a href="mailto:fle...@li...">the
+Flexible Task Graphs users mailing list</a> after first <a
+href="https://lists.sourceforge.net/lists/listinfo/flexotask-users">subscribing</a>
+to that mailing list.
+
+<br><hr><h2><a name="developer"/>Notes for Flexotask Core Developers</h2>
+
+<p>This section is still being written. It will describe the process
+for working directly with the source, rebuilding core features, and contributing
+to the project.
+
+<p>Meanwhile, we want to encourage participation. Please identify
+yourself by sending an email to <a
+href="mailto:fle...@li...">the Flexible Task
+Graphs developers mailing list</a> after first <a
+href="https://lists.sourceforge.net/lists/listinfo/flexotask-developers">subscribing</a>
+to that mailing list.
+
+<br><hr><h2><a name="toolWriter"/>Notes for Flexotask Tool Developers</h2>
+
+<p>This section is still being written. It will describe the interface between
+the development-time system and the runtime system and will document the XML format
+used by templates. The goal is to support the development of tools that generate
+Flexible Task Graphs and Flexotasks as their back-end artifacts.
+
+<p>Meanwhile, we want to support this kind of effort and the open
+source framework should allow it. Please identify yourself by sending
+an email to <a href="mailto:fle...@li...">the
+Flexible Task Graphs users mailing list</a> after first <a
+href="https://lists.sourceforge.net/lists/listinfo/flexotask-users">subscribing</a>
+to that mailing list.
+
</body>
</html>
Modified: trunk/flexotask/doc/palette.jpg
===================================================================
(Binary files differ)
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
