New Workflow Task
The following topics are covered in this tutorial:
- Reminder of the role of a workflow task
- Creation and configuration of a new workflow task
- Implementation of a new workflow task
- Using a new workflow task
Note that the two Eclipse installation asked for these two tutorials are different, you should use in the following the Preesm developer installation from Building Preesm.
Tutorial created the 12.10.2012 by K. Desnos
What is a Workflow Task?
A workflow is an executable graph that applies transformations to models (architecture, algorithm, ...). For example, the following workflow which is used in Tutorial Introduction, is designed to map and schedule an algorithm on an architecture, both defined in the executed scenario, and to generate the corresponding source code.
Within the workflow graph, each "vertex" - or "workflow task" - performs a specific action on one or several inputs. For example, the "HierarchyFlattening" workflow element takes as input an algorithm modeled with a hierarchical graph and outputs a flattened version of this graph.
How to create your own Workflow Task
In the remainder of this tutorial, we will create a new dummy workflow task whose purpose is to multiply by a given factor all the production and consumption rates of an algorithm graph. The tutorial is composed of the following steps:
- Creation and configuration of a new eclipse plugin
- Creation of a new workflow task
- Implementation of the new workflow task
- Registration of the new workflow task
- Test of the new workflow task
1. Creation and configuration of a new eclipse plugin
The Eclipse IDE integrates a powerful plugin mechanism that allows the seamless integration of new functionalities to the IDE. For example, Graphiti, DFTools, and Preesm each consist of a set of Eclipse plugins. Consequently, the easiest way to add new features to Preesm is to create your own plugin. To create a new plugin, in the Eclipse instance where the Building Preesm tutorial was done:
- Right-click in the package explorer and select "New->Other...".
- In the wizard, select "Plug-in Project" and click Next.
- Give a name to your project (following the Java Package Naming Conventions)
- Select the location of your project.
- Click Next.
- Fill up the details for your project
- uncheck the "UI contribution" box;
- if you plan to have special actions during the plug-in start/stop phases, check the "generate an activator..." box (see example here);
- click Next;
- Uncheck the "Create a plug-in using..." box and click on Finish.
The following project appears in your Package Explorer:
Before creating a new workflow task, you must first configure the dependencies of the plugin project:
- Open “META-INF/MANIFEST.MF” with the plugin manifest editor.
- In the “Dependencies” tab, click on the “Add” button of the “required Plug-ins” frame.
- Select the “org.ietr.dftools.workflow” plugin and click OK.
- In the “Properties” of the added plugin, empty the “Minimum Version” field.
- Save the modification of MANIFEST.MF.
To complete the plugin configuration, repeat steps 2 to 5 and add the following plugins to the list:
2. Creation of a new workflow task
The next step consists of creating the class that will implement the behavior of the workflow task:
- In the package Explorer, right-click on the plugin project and select “New->Class”
- Give a name the class and make it inherit from “AbstractTaskImplementation”.
- Click on Finish. The new class file will automatically open.
3. Implementation of the new workflow task
The monitorMessage() method returns a message that will be displayed in the Console of Preesm when the workflow task is executed. Here is an example of implementation for this task:
The getDefaultParameters() method returns a Map of Strings containing the parameters of the workflow task and their associated default values. These parameters can be edited in the “Properties” tab of Preesm when the workflow task is selected in a workflow. In our example, we have a unique parameter called factor whose default value is 1. Here is the corresponding code:
The execute(...) method is called when the workflow task is executed. Its inputs are:
- A Map containing the inputs of the workflow task (e.g. An algorithm graph, an architecture, ...)
- A Map containing the parameters of the workflow task
- An IProgressMonitor that can be used to track the progression of the workflow task
- A String containing the name given to the instance of the workflow task
- The Workflow where the workflow task is instantiated
The code of the execute method for our example is available here.
4. Registration of the new workflow task
Before being executed, the new workflow task must first be registered as an extension of org.ietr.dftools.workflow.tasks. To do that:
- Open the MANIFEST.MF file of your plugin and go to the "Extensions" tab.
- Click on "Add..." to open the "New Extension" Wizard.
- Select "org.ietr.dftools.workflow.tasks" and click "Finish".
- Fill the "Extension Element Details" as follows and save:
- Right-click on your extension name in the extension list and select "New->inputs"
- Right-click on "(inputs)" and select "New->input"
- Fill the "Extension Element Details" of the input as follows:
- Save and repeat steps 5 to 7 to add an output "SDF" to your workflow task. The extensions list should look like this:
Finally, the package containing the workflow task must be exported by the plugin in order to be usable by the workflow manager.
- In the MANIFEST.MF file, go to the "Runtime" tab.
- In the "Exported Packages" section, click on "Add..."
- Select the package containing the task class and click "OK"
- Save the MANIFEST.MF. The new Workflow task is now ready to be used.
5. Test of the new workflow task
- Launch Preesm as explained in the Building Preesm tutorial.
- Open a workflow (for example, the one given in Tutorial 1).
- In the workflow, create a new Task using the "Palette" on the right of the workflow editor.
- Give a name to your task.
- Select the newly added task and edit its "Basic" properties in the bottom of the window.
- Set the "plugin identifier" property with the id used to register the workflow.tasks extension.
- Save and go to the "Task Variables" properties of the workflow task. The "factor" parameter should appear. (If not, go back to the Preesm project, clean, rebuild and launch).
- Set the value of the "factor" parameter.
- Connect the task in the workflow. For example, insert it between the "srSDF" and the "LIST scheduler" tasks. To add a new connection, select "Data transfers" in the editor Palette and successively click on the source and target of the connection.
- Save the workflow and execute it as explained in Tutorial Introduction.
You can now do a few tests with the new workflow task. For example, try changing the factor parameter into a negative number or a string of characters. You can also put breakpoints in the code of the task to follow its execution step-by-step.
The complete plugin project built along this tutorial is available here.