// Generated from task.y - manual changes will be lost
ifdef::sidebartoc[]
include::_Sidebar.adoc[]
endif::[]


























Task declaration
----------------

Tasks define an execution context suitable for running the codels of
link:service{outfilesuffix}[activities]).

****
[horizontal]
(21) `*task                  ::=*` ::
   `"task"` <<grammar#dotgen-rule-identifier,`identifier`>> <<grammar#dotgen-rule-opt-properties,`opt-properties`>> `";"`
(125) `*opt-properties        ::=*` ::
   `[` `"{"` <<grammar#dotgen-rule-properties,`properties`>> `"}"` `]`
(126) `*properties            ::=*` ::
   `{` <<grammar#dotgen-rule-property,`property`>> `}`
(127) `*property              ::=*` ::
   <<grammar#dotgen-rule-component-property,`component-property`>> +
                              `|` <<grammar#dotgen-rule-interface-property,`interface-property`>> +
                              `|` <<grammar#dotgen-rule-task-property,`task-property`>> +
                              `|` <<grammar#dotgen-rule-service-property,`service-property`>> +
                              `|` <<grammar#dotgen-rule-codel-property,`codel-property`>> +
                              `|` <<grammar#dotgen-rule-throw-property,`throw-property`>>
****

A task may optionally define a state machine with
link:codel{outfilesuffix}[codels]. In this case, the state machine runs in
the background as soon as the component starts, independently of any
external service request. The state machine always starts in the `start`
state. If a codel yields to the `ether` state, the state machine stops.
When the component is shutdown, the `stop` codel (if it exists) is always
invoked.

In any case, the task is always available for processing external service
requests, no matter if it has its own state machine or not.

****
[horizontal]
(36) `*fsm-codel             ::=*` ::
   `"<"` <<grammar#dotgen-rule-event-list,`event-list`>> `">"` <<grammar#dotgen-rule-identifier,`identifier`>> `"("` <<grammar#dotgen-rule-codel-parameters,`codel-parameters`>> `")"` `"yields"` <<grammar#dotgen-rule-event-list,`event-list`>>
****














The task declaration also defines a few properties like a priority and a
stack size. They are not necessarily used by all templates, but this allows
to target real-time embedded systems.

****
[horizontal]
(22) `*task-property         ::=*` ::
   `(` `"period"` <<grammar#dotgen-rule-const-expr,`const-expr`>> <<grammar#dotgen-rule-time-unit,`time-unit`>> +
                              `|` `"delay"` <<grammar#dotgen-rule-const-expr,`const-expr`>> <<grammar#dotgen-rule-time-unit,`time-unit`>> +
                              `|` `"priority"` <<grammar#dotgen-rule-positive-int-const,`positive-int-const`>> +
                              `|` `"scheduling"` `"real-time"` +
                              `|` `"stack"` <<grammar#dotgen-rule-positive-int-const,`positive-int-const`>> <<grammar#dotgen-rule-size-unit,`size-unit`>> `)` `";"`
****

+period+::
  The granularity of the codel scheduler. Periodic task will sequence the
  codels they manage at that frequency. If unspecified, the task has no
  period and sequences the codels as fast as possible.

+delay+::
  The initial delay before starting the scheduler. This can be used to delay
  two tasks running at the same period in the same component.

+priority+::
  Can be used to prioritize different tasks whithin the same component.
  Priorites are expressed as a integer between 0 and 255 (0 beeing the
  highest priority and 255 the lowest). This may not
  be supported by all templates.

+scheduling real-time+::
  This indicates that the task requires real-time scheduling. This may not
  be supported by all templates.

+stack+::
  Defines the required stack size for this task (in bytes if no unit is
  given). The stack size should be big enough to run all codels that the
  task manages. The property can also be specified for all tasks, including
  implicit tasks defined by a template, at the component level. This may not
  be used by all templates.





































=== Example

The following declaration declares a task with an initialization codel
running only once when the task starts:

[source,C]
----
component foo {
  task t {
    codel <start> init_codel() yield ether;
  };
};
----

The following declare a periodic task, running some code in the background:

[source,C]
----
component foo {
  ids { long data };

  task t {
    priority 100;
    stack 64k;
    period 50ms;

    codel <start> do_init(out data) yield compute;
    codel <compute> do_compute(inout data) yield compute, stop;
    codel <stop> do_cleanup(in data) yield ether;
  };
};
----

// eof
