View source for Lib/sequencer offers Multitasking

[[Category: Library]]
The <tt>lib/sequencer</tt> library implements an event-driven, priority-based, cooperative multitasker. The sequencer library does not start new threads or any other separate processes. Unlike "pure" cooperative multitasking, a task cannot stop at any time (using a hypothetical <tt>yield</tt> feature) but only in known and stable states. The sequencer library does it this way to retain conformance to Eiffel principles.

The sequencer library concepts:

* the class [[library_class:LOOP_STACK|<tt>LOOP_STACK</tt>]] manages the multitasking;
* the class [[library_class:JOB|<tt>JOB</TT>]] represents a task. The task core is the <tt>continue</tt> feature, during the execution of which the task controls the whole system;
* the class [[library_class:EVENTS_SET|<tt>EVENTS_SET</tt>]] describes the condition(s) in which a task can be executed.

We will successively document each of these concepts:

== The multitasking manager ==
The class [[library_class:LOOP_STACK|<tt>LOOP_STACK</tt>]] is in charge of managing the multitasking. It is used in two steps:
* initialization: creation of the <tt>LOOP_STACK</tt> object and adding the task(s) to be executed
* execution: execution of the <tt>run</tt> feature

Of course, additional tasks can be added during the execution. The manager can also be stopped, thanks to the <tt>break</tt> feature.

Note that the loop stack contains many execution loops ([[library_class:LOOP_ITEM|<tt>LOOP_ITEM</tt>]]). This allows, for instance, the implementation of a kind of ''modality'' (e.g. the modal windows in [[lib/vision|Vision]]).

== Tasks ==

A task has a life cycle represented by the features executed by the manager (indeed a [[library_class:LOOP_ITEM|<tt>LOOP_ITEM</tt>]] hence the export clauses of those features).

# <tt>prepare</tt> allows preparing the task; in this phase, the task sets the events upon which it wants to be activated. The [[library_class:EVENTS_SET|<tt>EVENTS_SET</tt>]] object is an object upon which one can set conditions (thanks to its <tt>expect</tt> feature).
# <tt>is_ready</tt> allows testing if the task has really been activated. The [[library_class:EVENTS_SET|<tt>EVENTS_SET</tt>]] object is an object upon which one can test conditions (thanks to its <tt>event_occurred</tt> feature).
# <tt>continue</tt> contains the execution body of the task, and is executed upon task activation.
# <tt>done</tt> tells if the task has finished its execution. If so, it will be removed from the execution loop. Otherwise, the cycle begins again.
# <tt>restart</tt> allows reinserting a task in the execution loop.

The <tt>restart</tt> feature is seldom useful. See [[lib/vision|Vision]] for some use cases.

== Execution conditions ==

The class [[library_class:EVENTS_SET|<tt>EVENTS_SET</tt>]] allows setting and test conditions ([[library_class:EVENT_DESCRIPTOR|<tt>EVENT_DESCRIPTOR</tt>]]s).

The possible conditions are:

* '''Time''': this allows to create periodic tasks. See the classes [[library_class:PERIODIC_JOB|<tt>PERIODIC_JOB</tt>]], [[library_class:BACKGROUND_JOB|<tt>BACKGROUND_JOB</tt>]], and [[library_class:TIME_EVENTS|<tt>TIME_EVENTS</tt>]];
* '''Input-output''':
** ''Data on an input stream'': this allows to build tasks that wait for input data to be available (feature [[library_class:INPUT_STREAM|<tt>INPUT_STREAM</tt>]]<tt>.event_can_read</tt>),
** ''Data on an output stream'': this allows to build tasks that wait until they can write on an output stream (feature [[library_class:OUTPUT_STREAM|<tt>OUTPUT_STREAM</tt>]]<tt>.event_can_write</tt>);
* '''Network''': this allows to build tasks waiting network connections (feature [[library_class:SOCKET_SERVER|<tt>SOCKET_SERVER</tt>]]<tt>.event_connection</tt>).

== Tasks scheduling ==

The manager implements the following cycle:

* call to the feature [[library_class:EVENTS_SET|<tt>EVENTS_SET</tt>]]<tt>.reset</tt>;
* call to the feature [[library_class:JOB|<tt>JOB</tt>]]<tt>.prepare</tt> on each task;
* call to the feature [[library_class:EVENTS_SET|<tt>EVENTS_SET</tt>]]<tt>.wait</tt> to wait for at least one condition to happen;
* call to the feature [[library_class:JOB|<tt>JOB</tt>]]<tt>.is_ready</tt> on each task;
* for all the ready tasks, call to the feature [[library_class:JOB|<tt>JOB</tt>]]<tt>.continue</tt>;
* for those tasks, call to the feature [[library_class:JOB|<tt>JOB</tt>]]<tt>.done</tt> and if relevant, remove the task;
* and back to the beginning.

== Priorities ==

Tasks execution is by priority order. Only the ready task with the ''lowest'' priority is executed. All other tasks, even if ready, will have to wait until no other task with a lower priority is ready.

 -note: we need to document how many priority levels <br> are supported and how the scheduling works when multiple or all tasks were given<br> an identical priority level. Would the scheduler then resort to some sort<br> of round-robin method? By what rules? Apparently '''not''' by evaluating the duration of the<br> wait for next execution, see the '''LOOP_ITEM.run''' method.  /HZ

== Libraries using the sequencer ==

* [[lib/net]]: servers usually allow many simultaneous connections. This is implemented with the sequencer library.

* [[lib/vision]]: the event manager loop is implemented with a sequencer.