Menu
▾
▴
[flexotask-commits] SF.net SVN: flexotask:[100] trunk/flexotask/doc
|
From: <jsa...@us...> - 2008-11-14 15:32:03
|
Revision: 100
http://flexotask.svn.sourceforge.net/flexotask/?rev=100&view=rev
Author: jsauerbach
Date: 2008-11-14 15:32:01 +0000 (Fri, 14 Nov 2008)
Log Message:
-----------
Further progress on documentation.
Modified Paths:
--------------
trunk/flexotask/doc/flexotaskProgramming.html
Added Paths:
-----------
trunk/flexotask/doc/connectionProperties.jpg
trunk/flexotask/doc/palette.jpg
trunk/flexotask/doc/paletteControl.jpg
trunk/flexotask/doc/simpleGraph.jpg
trunk/flexotask/doc/taskHover.jpg
trunk/flexotask/doc/taskProperties.jpg
Property Changed:
----------------
trunk/flexotask/doc/
Property changes on: trunk/flexotask/doc
___________________________________________________________________
Modified: svn:ignore
- com
resources
package-list
*.css
allclasses-frame.html
allclasses-noframe.html
constant-values.html
help-doc.html
index.html
overview-frame.html
overview-summary.html
serialized-form.html
exotaskProgramming.txt
screenshots.htm
+ com
resources
package-list
*.css
allclasses-frame.html
allclasses-noframe.html
constant-values.html
help-doc.html
index.html
overview-frame.html
overview-summary.html
serialized-form.html
exotaskProgramming.txt
screenshots.htm
screenshots_files
Added: trunk/flexotask/doc/connectionProperties.jpg
===================================================================
(Binary files differ)
Property changes on: trunk/flexotask/doc/connectionProperties.jpg
___________________________________________________________________
Added: svn:mime-type
+ image/jpeg
Modified: trunk/flexotask/doc/flexotaskProgramming.html
===================================================================
--- trunk/flexotask/doc/flexotaskProgramming.html 2008-11-14 15:31:39 UTC (rev 99)
+++ trunk/flexotask/doc/flexotaskProgramming.html 2008-11-14 15:32:01 UTC (rev 100)
@@ -34,7 +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="#creating">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>
@@ -350,8 +350,10 @@
<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:
+At present, this builder writes status messages and some error
+messages to to the console (it also displays errors and warnings using
+Eclipse markers and entries in the <b>Problems View</b>). You may
+have noticed its presence when it issued messages like the following:
<pre>
Running Flexotask Builder ...
@@ -457,45 +459,67 @@
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.
+<p>Before you can visit the IBM AlphaWorks Update site, which provides
+this support, you need a (no cost) IBM identity (this is used with
+IBM's AlphaWorks, DeveloperWorks, Academic Initiative, and other
+online facilities). Your IBM identity is typically an email address
+registered with IBM and an associated password. If you have never
+gone through this registration process, you can begin <a
+href="https://www.ibm.com/account/profile/us?page=reg">here</a>. The
+same identity will work with DeveloperWorks to obtain the WebSphere
+Real Time VM itself.
+<p>Once you have an IBM identity, 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><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.
+click <b>Next</b>. You may already have an update site called <b>IBM
+AlphaWorks Update Site</b>. If not, click <b>Add Remote Site</b>
+and enter the following:
+<pre>
+Name: IBM AlphaWorks Update Site
+URL: http://awwebx04.alphaworks.ibm.com/ettktechnologies/updates
+</pre>
+Click <b>Ok</b> and the new update site should appear. Under that
+site, select the <b>Flexible Task Graphs Runtimes</b> category and
+complete the dialog to install the feature. You will be prompted for
+your IBM ID and password during the process.
<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
-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.
+labelled <b>IBM AlphaWorks Update Site</b> (or perhaps listed under
+its URL, which is
+<b>http://awwebx04.alphaworks.ibm.com/ettktechnologies/updates</b>)
+then click <b>New Site</b> and enter that URL. Press <b>Ok</b> and
+the site should appear. Under that site, select the <b>Flexible Task
+Graphs Runtimes</b> category and complete the dialog to install the
+feature. You will be prompted for your IBM ID and password during the
+process.
<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
-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. 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.
+DeveloperWorks</a>. You will need to establish an IBM id (if you did
+not already do so in order to access <b>IBM AlphaWorks</b>), answer
+some survey questions, and adhere to the terms of the license. As of
+this writing there are two versions of WRT 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>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 the same functionality appears to work on Version 2
and we will emphasize support for the latest version in the long run.
@@ -625,8 +649,7 @@
<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).
+<b>true</b>).
<li><b>setTimingData</b> to establish the timing grammar for the graph
and any global properties that go with that timing grammar. More on
@@ -637,6 +660,11 @@
href="com/ibm/realtime/flexotask/template/FlexotaskTemplate.html">in
the javadoc</a>.
+<p>There is also some additional semantic discussion of these
+properties in conjunction with the <a href="#editorGlobal">Flexotask
+Editor</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
@@ -858,6 +886,11 @@
basis as tasks.
</ul>
+<p>A connection also has an implicit property, which is its data type.
+This is inferred from the types of the ports that the connection
+connects. It is illegal for a connection to connect ports of unlike
+type.
+
<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
@@ -913,27 +946,282 @@
<br><hr><h4><a name="editor"></a>The Flexotask Editor</h4>
+<p>The editor is useful when a task graph has more than a few elements
+and so building it up programmatically would be tedious. The editor's
+graphical view also allows for a conceptual grasp of what is going on.
+Although Flexible Task Graphs are a programming system, not a modeling
+system, the graphical editor provides a view that is closer to what a
+modeling system might provide. The following outline provides quick
+access to the information in this section.
+
+<ul>
+<li><a href="#editorGeneral">Getting Started with the Editor</a>
+<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="#editorConnection">Specifying Connection Properties</a>
+<li><a href="#editorPort">Specifying Ports and their Properties</a>
+</ul>
+
+<br><hr><h5><a name="editorGeneral"></a>Getting Started with the Editor</h5>
+
<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).
+create an XML-format Flexotask template stored in that file.
-<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>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 a class in your application whose identity you
+can use to find the <b>.ftg</b> as a resource (an example 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 it has a blank canvas, a gear-like
+icon on the tab along with the file name and decoration at the upper
+right hand edge that represents a hidden palette. Under Eclipse
+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>The palette will also fly out temporarily when you simply place the
+mouse cursor on the control. In any case, the palette can be
+re-hidden as you wish. Under Eclipse 3.3, the palette control and the
+palette itself look slightly different but provide the same options
+and behaviors.
+
+<p>A properties view is created (or unburied if you already have one)
+as a side-effect of opening the editor. You use this Properties view
+to augment information in the editor's graphical view, as explained in
+subsequent sections. Properties are altered by clicking in the
+<b>Value</b> box of the property you want to change. In general, the
+editor property sheets will allow free text entry when that is
+appropriate. Otherwise, clicking in the <b>Value</b> box will cause
+an appropriate structured control to appear (a combo box or one or
+more buttons, which bring up secondary dialogs). New values do not
+take effect until you either press <b>Enter</b> or direct the focus to
+another area.
+
+<p>As mentioned in the Flexible Task Graphs paper and explained in
+more detail in the LCTES 2007 Exotasks paper, the way that real-time
+scheduling is expressed can vary according to the choice of a timing
+grammar. There are always at least two choices provided, but there
+will be more if additional timing grammar plugins have been installed.
+You need to select your timing grammar before entering other elements
+of the task graph. One of the provided timing grammars must be
+dragged and dropped into the canvas to establish timing grammar before
+any tasks and connections can be established. On the canvas, a timing
+grammar is represented by a box that is not connected to any other
+box. By convention, we usually place it at the top of the canvas or
+near one of the edges.
+
+<p>Once a timing grammar has been established, tasks (which may be
+normal tasks, predicates, or communicators) can be dragged into the
+canvas. The connection tool may then be selected to draw connections
+between the tasks. Using this technique one can quickly build up a
+task graph with the desired topology as in this picture.
+
+<p><img width=401 height=265 src="simpleGraph.jpg"/>
+
+<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
+connections are black. To discover what is missing or incorrect, rest
+the cursor on a yellow or red element in the graph to see the tooltip
+text. For example, here is the tooltip text for a newly created task,
+showing that the implementation class is missing.
+
+<p><img width=201 height=113 src="taskHover.jpg"/>
+
+<p>To fill in missing information, use the <b>Properties</b> view.
+Single-click on any task or connection to bring up the properties for
+that task or connection. Single-click on the timing grammar box to
+bring up timing-related global properties. Single-click on an
+unoccupied portion of the canvas to bring up the general global
+properties.
+
+<p>Subsequent sections discuss the specifics of specifying global
+properties, global timing properties, task properties, connection properties, and ports (with
+their properties) using the editor.
+
+<br><hr><h5><a name="editorGlobal"/>Specifying Global Properties</h5>
+
+<p>Single-click on an unoccupied portion of the canvas to cause the
+<b>Properties</b> view to show general global properties. The
+property sheet for these properties looks like this.
+
<p><img width=377 height=134 src="initialProperties.jpg"/>
+<p>Change the <b>Allocation</b> or <b>Synchronization</b> properties
+from <b>allowed</b> to <b>forbidden</b> in order to restrict your task
+graph from allocating objects or synchronizing. Change the <b>Stable
+Mode</b> property to your preferred paradigm for using memory, which
+may be one of <b>all classes stable</b>, <b>use marker interface</b>,
+<b>listed explicitly</b>, or <b>inferred</b>. If you use <b>listed
+explicitly</b>, then modify the <b>Stable Classes</b> property to list
+the classes to be treated as stable. There is more information about
+the semantics of the four stable classes options in <a
+href="#templateStable">the related API discussion</a>.
+
+<p>Note that even when allocation is forbidden, objects of classes
+that extend <b>Throwable</b> can always be allocated (the prohibition
+covers all other objects). The expectation is that your program will
+allocate <b>Throwable</b> objects only to deal with terminating
+exceptions and will not use exceptions for routine control flow.
+
+<p>In the Flexible Task Graphs paper in LCTES 2008 (as well as in the
+earlier Exotask 2007 paper) we stated that synchronizations by
+strongly isolated task graphs have no effect. We have implemented
+this feature experimentally, but, in the code that we make publically
+available, the implementation of this aspect of the design is
+incomplete because we have not had an opportunity to release a version
+of the WebSphere Real Time VM with the necessary hooks. The reality
+is that most synchronizations (in both strongly and weakly isolated
+graphs) have no effect because the partitioning of objects into
+task-specific memory areas discourages access to those objects by more
+than one thread at a time. However, both strongly and weakly isolated
+graphs that have references to objects on the public heap and that
+synchronize on those objects may, in fact, experience delays due to
+contention.
+
+<br><hr><h5><a name="editorGlobalTiming"/>Specifying Global Timing Properties</h5>
+
+<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
+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
+seconds, milliseconds, microseconds, or nanoseconds according to
+whether the value is suffixed with <b>s</b>, <b>m</b>, <b>u</b>, or
+<b>n</b>. The default unit is milliseconds if no suffix is provided.
+For example, <b>500u</b> means 500 microseconds.
+
+<br><hr><h5><a name="editorTask"/>Specifying Task Properties</h5>
+
+<p>The task properties are shown in the following illustration.
+
+<p><img width=270 height=214 src="taskProperties.jpg"/>
+
+<ul>
+<li><b>Task Name</b> establishes a name for the task. Every task in a
+Flexible Task Graph must have a unique name.
+
+<li><b>Implementation Class</b> establishes the implementation class
+for the task. The <b>Change</b> button for this property gives you an
+opportunity either to find an existing implementation class that you
+wrote previously or else to create a new class. The dialogs for the
+two cases are the familiar <b>Find Type</b> and <b>New Class</b>
+dialogs of Eclipse.
+
+<li><b>Isolation</b> presents a combo box that can be set to either
+<b>strong</b> or <b>weak</b>.
+
+<li><b>Parameter Class</b> establishes the type of a default parameter
+that will become 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>Parameter Value</b> establishes the value of a default parameter
+whose type is given by <b>ParameterType</b>. The syntax of this
+expression is <a
+href="com/ibm/realtime/flexotask/template/FlexotaskTaskTemplate.html#setParameterValue(java.lang.String)">explained
+as part of the API</a>.
+
+<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
+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>
+
+<p>Tasks have ports, and information about the task's ports is
+displayed under the <b>Input</b> and <b>Output</b> categories, as
+shown in the screenshot. However, these values cannot be modified in
+the task property sheet. The editor provides for modification of
+ports and their properties through the <em>connection</em> property
+sheets, as explained <a href="#editorPort">below</a>
+
+<p>Predicates have properties quite similar to tasks except that no
+output ports are displayed. However, communicators have a different
+set of properties, as discussed in the next section.
+
+<br><hr><h5><a name="editorCommunicator"/>Specifying Communicator Properties</h5>
+
+<p>Under construction.
+
+<br><hr><h5><a name="editorConnection"/>Specifying Connection Properties</h5>
+
+<p>The connection properties are shown in the following illustration.
+
+<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.
+
+<ul>
+<li><b>Connection Name</b> establishes a name for the connection. If
+you do not edit this property, the system-generated name (which is
+based on the ports that are connected by the connection) is usually
+sufficient. This name is used only in diagnostic messages.
+
+<li><b>Connection Data Type</b> establishes the type of data that will
+pass over the connection (as the name of a Java class). The
+<b>Change</b> button for this property brings up the familiar <b>Find
+Type</b> dialog. Any Java class that is legal for a Flexotask to use
+(based on the rules covered in the <a href="#tasks"><b>Writing
+Flexotasks</b> section</a>) is legal to transmit on the connection.
+Subclasses of the chosen type may also be transmitted (e.g. if this
+property is set to <b>java.lang.Object</b> then any legal object may
+be transmitted). But note that the <b>Connection Mode</b> property
+can restrict what may be transmitted independently of the type.
+
+<li><b>Connection Mode</b> presents a combo box that can be set to
+<b>deepclone</b> or <b>hybrid</b> or <b>byref</b>. 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 (part of the template API).
+
+<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
+and connections. In this particular case, you can modify the property
+to specify that the connection 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>). Executing a connection means
+moving one data item from the output port source of the connection to
+the input port target of the connection.
+</ul>
+
+<br><hr><h5><a name="editorPort"/>Specifying Ports and their Properties</h5>
+
+<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).
+
+<p>Section under construction.
+
<br><hr><h3><a name="tasks"></a>Writing Flexotasks</h3>
+<p>Under construction.
+
</body>
</html>
Added: trunk/flexotask/doc/palette.jpg
===================================================================
(Binary files differ)
Property changes on: trunk/flexotask/doc/palette.jpg
___________________________________________________________________
Added: svn:mime-type
+ image/jpeg
Added: trunk/flexotask/doc/paletteControl.jpg
===================================================================
(Binary files differ)
Property changes on: trunk/flexotask/doc/paletteControl.jpg
___________________________________________________________________
Added: svn:mime-type
+ image/jpeg
Added: trunk/flexotask/doc/simpleGraph.jpg
===================================================================
(Binary files differ)
Property changes on: trunk/flexotask/doc/simpleGraph.jpg
___________________________________________________________________
Added: svn:mime-type
+ image/jpeg
Added: trunk/flexotask/doc/taskHover.jpg
===================================================================
(Binary files differ)
Property changes on: trunk/flexotask/doc/taskHover.jpg
___________________________________________________________________
Added: svn:mime-type
+ image/jpeg
Added: trunk/flexotask/doc/taskProperties.jpg
===================================================================
(Binary files differ)
Property changes on: trunk/flexotask/doc/taskProperties.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.
|
