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 the Eiffel principles.

The principle is:

* 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 those 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 loops stack is composed of 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 to prepare 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 to test 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 if the task is really activated.
# <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 to reinsert 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 to set 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 are executed by priority order. Only the ready task with the ''lowest'' priority is executed. The others, even if ready, will have to wait a future time when 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 to accept many simultaneous connections. This is implemented with the sequencer library.

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