The task module definition file provides a way for Fabric developers to expose methods contained in their C, Java, and .NET task modules to the Fabric. These methods can be referenced as actions from process flow states to be executed as part of a client request or configured to run in the background of the task service.
Each task module is defined in a single XML file and should contain all of the task definitions for that module. Note: the ordering of child elements within a parent element is enforced.
Example task definition file
<?xml version='1.0'?>
<!DOCTYPE module SYSTEM 'ModuleDefinition.dtd'>
<module file="simple-fabric-task.dll" implementation="DLL">
<task name="fetch_library_path" />
<task name="pi" type="exclusive" busy-wait-timeout="3">
<method>calculate_pi</method>
</task>
</module>
Table - Task Module XML Description
| Element |
Description |
| module |
The module element has three attributes: file, implementation, and className.
| Attribute |
Use |
Description |
| file |
required |
The task module's filename. |
| implementation |
required |
Identifies the tasks' run-time environment. This attribute has three possible values.
- .NET for task methods implemented in a class within a .NET assembly.
- DLL for task functions implemented in a Linux C shared object or Windows C DLL.
- Java for task methods implemented in a Java class that may be part of a Java jar.
|
| className |
required if implementation is .NET or Java |
The name of the Java or .NET class that implements the task methods. This attribute is required for .NET and Java, and is ignored implementation is DLL. |
| Element |
Cardinality |
Description |
| task |
1..n |
This declares the name and type of your task |
| affinity-task |
1..n |
This defines your affinity task |
Below is an example of a module element with a DLL implementation
<module file="tutorial_tasks.so" implementation="DLL" >
A path relative to the Fabric application is also supported.
<module file="my-tasks/simple-task.dll" implementation="DLL" >
In .NET and Java, the className identifies the class containing the task implementation. The className value is the fully-qualified name of the class including namespace.
<module file="VBdotnet.dll" implementation=".NET" className="Acme.VBTask">
In Java, the className identifies the location of the Java class file. The className value is the fully-qualified name of the class including package.
<module file="JavaTask.class" implementation="Java" className="com.acme.tasks.JavaTask">
In the following Java example the task class is inside a jar.
<module file="acme.jar" implementation="Java" className="com.acme.tasks.JavaTask">
|
| task |
The task element has at least two attributes: name, type. Additional attributes are available based on the task type.
| Attribute |
Use |
Description |
| name |
required |
This defines the name of the task action that can be referenced by process flows. The name may be the exact name of the function or method to be called, or it may be an alias. If the name is an alias, then a corresponding method element must be used. This attribute is case sensitive. |
| type |
optional |
Indicates if the task is unlimited, limited, exclusive, or background. Defaults to unlimited if not set. |
| min |
optional |
Minimum number of task instances available per Fabric. |
| max |
optional |
Maximum number of task instances available per Fabric. |
| percentage |
optional |
Percentage of Fabric workers that will maintain an instance of this task. |
| instances |
optional |
Specific number of task instances available per Fabric. |
| retryDelay |
optional |
Amount of time, in milliseconds, a task service waits before retrying the execute of a background task that returned failure. |
| busy-wait-timeout |
optional |
Amount of time, in seconds, the fabric waits for an available worker when workers running exclusive tasks are busy. |
| Element |
Cardinality |
Description |
| method |
0..1 |
Name of the actual execute method. Only needed if the method name differs from the task name attribute. |
| onStartup |
0..1 |
Name of the method to be executed by each fabric worker when it loads the task. |
| onShutdown |
0..1 |
Name of the method to be executed by each fabric worker when it unloads the task. |
| isAvailable |
0..1 |
Method that can be called by the fabric to determine if the task should be advertised as available on a worker. |
The fabric is capable of running multiple, concurrent instances of a task on a worker or CPU. However, this is not always desirable. Appistry EAF allows you to configure a task by classifying it as one of four types and adding parameters based on the task type. The table below provides a basic overview of the four task types. For in depth explanations, refer to the appropriate task's tutorial.
| Task Type |
Characteristics |
Configuration |
Tutorial |
| Unlimited |
- No restrictions
- Multiple instances may run concurrently on multiple workers in the fabric
- Multiple requests for the task are serviced concurrently depending on available memory and CPU
|
Task XML file |
Hello World with Process Flows and tasks |
| Limited |
- Only a specified number of instances may run concurrently in the fabric (for example, a limited task may be configured to run on 2 out of 10 workers)
- A worker may run multiple instances of the task
- Multiple requests for the task are serviced concurrently depending on configuration, available memory, and CPU
|
Task XML file |
|
| Exclusive |
- Only a specified number of instances may run concurrently per worker or per CPU (for example, an exclusive task will run on every worker but be restricted to only one instance at a time based on worker or CPU)
- The fabric performs load control to balance requests for exclusive tasks across the fabric
- When multiple requests for an exclusive task arrive on a single worker, the requests are executed in a gated fashion. For example, if exclusive tasks are configured to allow two concurrent per worker, then two requests are serviced at a time while other requests wait their turn.
- Good for long running tasks (several seconds or more) or CPU intensive
|
Task XML file and fabric.cfg
|
Computing Pi using Exclusive Tasks tutorial |
| Background |
- Runs constantly waiting for work (like a unix daemon or Windows service)
- Background tasks are not called from a process flow as part of a client request, but rather get "work" as defined by the task implementer. For example, the background task might monitor a queue in fabric accessible memory (FAM), read from a socket. or poll a service external to the fabric.
- Since it is not part of a fabric request, background tasks do not have the same inherent reliability as the other task types
|
Task XML file |
|
Unlimited Tasks
The unlimited task type does not have additional attributes beyond the mentioned name and type.
Please note the first uses the exact name of the method to be called, and the second uses an alias.
<task name="calculateShipmentDate" type="unlimited"/>
or
<task name="calcShipDate" type="unlimited">
<method>calculateShipmentDate</method>
</task>
Limited Tasks
Limited tasks define the following additional attributes:
- The min attribute indicates the minimum number of instances this task can run at one time. This attribute must be greater than zero.
- The max attribute indicates the maximum number of instances this task can run at one time. This attribute must be greater than the minimum value.
- The percentage attribute indicates the percentage of workers that can run one instance of the task.
- The instances attribute indicates the specific number of instances this task can run at one time.
For limited tasks, the percentage attribute must be greater than zero and less than or equal to 100. The min and max values override this value. For example, if an application fabric consists of 100 workers and a limited task has a percentage value of 10, a min value of 2 and a max value of 5, only 5 instances of this task can run at the same time.
<task name="enterOrderToDB" type="limited" min="5" max="20" percentage="25">
Exclusive Tasks
Exclusive tasks define the following additional attribute:
- The busy-wait-timeout attribute indicates the amount of time, in seconds, the fabric waits for an available worker when workers running exclusive tasks are busy. This attribute is only available if the task type is exclusive. A value of INFINITE means that the fabric will wait indefinitely.
<task name="computePi" type="exclusive" busy-wait-timeout="2">
Background Tasks
Background tasks define the following additional attributes:
- The percentage attribute indicates the percentage of workers that can run one instance of the task. If a background task includes the instances attribute, the percentage attribute is not available.
- The instances attribute indicates the total number of instances of the task running in the fabric at one time. This number may be greater than the number of workers in the fabric. If a background task includes the percentage attribute, the instances attribute is not available.
- The retryDelay attribute indicates the amount of time, in milliseconds, the fabric waits before attempting to rerun the execute method. This delay applies only if an error occurs when the fabric is trying to rerun the execute method. Background tasks that complete successfully immediately begin processing the next task. The failure is triggered when the background task's error message is set. Use the following API to set the error message in your background task:
| Language |
API/Annotation |
| C |
fab_req_set_task_failure |
| .NET |
[BGTaskFailureMessage] |
| Java |
@BGTaskFailureMessage |
For background tasks, the percentage attribute must be greater than zero and may be greater than 100. For example, if an application fabric consists of 100 workers and a background task has a percentage value of 150, 150 instances of this task can run at the same time.
<task name="processVendorFeedEvents" type="background" percentage="10" retryDelay="10000">
or
<task name="processVendorFeedEvents" type="background" instances="1" retryDelay="10000">
|
| affinity-task |
The affinity-task element identifies a method or function whose purpose is to help the fabric direct work to a worker with the needed capacity, resource, etc. for a specific piece of work requested by a process flow state. The affinity-task is specified in one or more process flow definitions, and a corresponding entry in the Task definition file is required.
| Attribute |
Use |
Description |
| name |
required |
This defines the name of the task action. The name may be the exact name of the function or method to be called, or it may be an alias. If the name is an alias, then a corresponding method element must be used. This attribute is case sensitive. |
| Element |
Cardinality |
Description |
| method |
0..1 |
Name of the actual execute method. Only needed if the method name differs from the task name attribute. |
The name attribute is the name of the affinity task and must be identical to the affinity task name used in the process flow. The name may be the exact name of the function or method to be called, or it may be an alias. If the name is an alias, then a corresponding method element (see below) must be used. This attribute is case sensitive.
<affinity-task name="isDataInLocalCache"/>
or
<affinity-task name="checkCache">
<method>isDataInLocalCache</method>
</affinity-task>
|
| method |
The method element identifies a task's actual execute function or method. This element is a child of the task and affinity-task elements and is only required when the name attribute of the parent element is an alias for the actual function or method name. Below is an example of a method element.
Please note the first uses the exact name of the method to be called, and the second uses an alias.
<task name="calculateShipmentDate" type="unlimited"/>
<task name="calcDelivery" type="unlimited">
<method>calculateDeliveryDate</method>
</task>
|
| onStartup |
The onStartup element names a function that accepts no input values. This function allows you to setup a task for processing. Each fabric application is hosted by a task service. The onStartup function of a given task is called once and only once when the task service starts up. An example of an onStartup function is opening a connection to a database. This is an optional element, and a child of the task element, and must follow the method element. Below is an example of an onStartup element.
<onStartup>openConnection</onStartup>
|
| onShutdown |
The onShutdown element names a function that accepts no input values. This function allows you to cleanup a task before shutdown. Each fabric application is hosted by a task service. The onShutdown function of a given task is called once and only once when the task service shuts down. An example of an onStartup function is closing a database connection. This is an optional element, and a child of the task element, and must follow the onStartup element. Below is an example of an onShutdown element.
<onShutdown>closeConnection</onShutdown>
|
| isAvailable |
Deprecated: You can use affinity tasks for this functionality and more.
The isAvailable element names a boolean method or function that accepts no input values. This method or function returns true or false to indicate if the worker is available to perform a function at that time. For example, if the worker loses the database connection, the isAvailable returns false until the connection is restored and the worker does not accept work that requires this function. This is an optional element, and a child of the task element, and must follow the onShutdown element. The actual method or function must be implemented by the fabric task developer.
<isAvailable>myIsAvailableMethod</isAvailable>
|
Examples of each type
Unlimited task
<?xml version='1.0'?>
<!DOCTYPE module SYSTEM 'ModuleDefinition.dtd'>
<module file="JavaTasks.jar" implementation="Java" className="MyJavaTask">
<task name="executeJob"/>
<affinity-task name="shouldExecute"/>
</module>
<?xml version='1.0'?>
<!DOCTYPE task SYSTEM 'ModuleDefinition.dtd'>
<module file="tutorial_tasks.dll" implementation="DLL" >
<task name="myUnlimitedTask" type="unlimited">
<method>executeJob</method>
<onStartup>setup</onStartup>
<onShutdown>cleanup</onShutdown>
</task>
</module>
Limited task
<?xml version='1.0'?>
<!DOCTYPE task SYSTEM 'ModuleDefinition.dtd'>
<module file="tutorial_tasks.dll" implementation="DLL" >
<task name="myLimitedTask" type="limited" min="1" max="5">
<method>enterOrderToDB</method>
<onStartup>openConnection</onStartup>
<onShutdown>closeConnection</onShutdown>
</task>
</module>
Exclusive task
<?xml version='1.0'?>
<!DOCTYPE task SYSTEM 'ModuleDefinition.dtd'>
<module file="tutorial_tasks.dll" implementation="DLL">
<task name="myExclusiveTask" type="exclusive" busy-wait-timeout="3">
<method>executeJob</method>
</task>
</module>
Background tasks
<?xml version='1.0'?>
<!DOCTYPE task SYSTEM 'ModuleDefinition.dtd'>
<module file="tutorial_tasks.dll" implementation="DLL">
<task name="myBackgroundTask" type="background" instances="1" retryDelay="1000">
<method>executeDaemon</method>
</task>
</module>
|
|
