Oberon || Library || Module Index || Search Engine || Definition || Module

Ulm's Oberon Library:
Tasks

NAME

Tasks - general task management

SYNOPSIS

CONST taskGroupMismatch = 0;
CONST dispatchTerminatedTask = 1;
CONST wrongScheduler = 2;
CONST invalidSet = 3;
CONST errorcodes = 4;
TYPE ErrorEvent = POINTER TO ErrorEventRec;
TYPE ErrorEventRec =
   RECORD
      (Events.EventRec)
      errorcode: SHORTINT;
   END;
VAR errormsg: ARRAY errorcodes OF Events.Message;
VAR error: Events.EventType;



TYPE Task = POINTER TO TaskRec;
TYPE TaskRec = RECORD (Disciplines.ObjectRec) END;
TYPE TaskGroup = POINTER TO TaskGroupRec;
TYPE TaskGroupRec = RECORD (Disciplines.ObjectRec) END;



(* codes returned by the dispatch procedure *)
CONST terminate = 0;
CONST suspend = 1;
CONST waitfor = 2;



TYPE CreateProc = PROCEDURE (VAR task: Task; cr: Coroutines.Coroutine);



PROCEDURE Current() : Task;
PROCEDURE CurrentGroup() : TaskGroup;



PROCEDURE InitGroup(tg: TaskGroup);
PROCEDURE Init(task: Task; cr: Coroutines.Coroutine; tg: TaskGroup);
PROCEDURE Dispatch(tg: TaskGroup; task: Task;
                   setOfTrueConditions: Conditions.ConditionSet;
                   VAR code: SHORTINT;
                   VAR conditionSet: Conditions.ConditionSet);



PROCEDURE Suspend;
PROCEDURE Select(conditionSet: Conditions.ConditionSet;
                 VAR setOfTrueConditions: Conditions.ConditionSet);
PROCEDURE WaitForOneOf(conditionSet: Conditions.ConditionSet);
PROCEDURE WaitFor(condition: Conditions.Condition);
PROCEDURE Terminate;
PROCEDURE Disconnect;



PROCEDURE Create(VAR task: Task; cr: Coroutines.Coroutine);
PROCEDURE SetupDefaultGroup(create: CreateProc);

DESCRIPTION

Tasks offers synchronisation primitives for tasks and is a general interface for task schedulers. Each task is represented by a coroutine which is free to use and to create other coroutines which do not correspond necessarily to a Task. Tasks are organized in groups and each group is controlled by a scheduler. The scheduler itself belongs to a task of another group. Thus, multiple and concurrent schedulers are possible.

Task primitives

Tasks are not created by Tasks directly but by one of the running schedulers. Because these schedulers are not always known or the choice of a scheduler does not matter, Tasks supports a default task group. This default task group may be announced by SetupDefaultGroup (this is currently done by SysMain). Create causes then cr to be passed to the create interface procedure which is expected to create a new task for cr which is returned in task. All tasks created via create should belong to one default task group which is a direct descendant of the main task group.

Tasks are in one of four states:

ready: Tasks in this state are ready to run. Their associated scheduler decides (via Dispatch) when this task will become active. This is the initial state of newly created coroutines.
running: The state of the currently running coroutine. This state is only left by one of the primitives Select, WaitFor, WaitForOneOf, Suspend, or Terminate.
waiting: Tasks which are waiting for conditions to become TRUE are in this state.
terminated: This is the final state which is reached only by calling Terminate or Disconnect by the coroutine itself.

Select, WaitForOneOf, and WaitFor cause a state transition from running to waiting until one of the given conditions becomes TRUE (see Conditions). Then the state will change from waiting to ready. Select returns the set of true conditions in setOfTrueConditions. Note that neither Select nor WaitForOneOf accept an empty condition set or NIL.

Suspend causes a state transition from running to ready.

Terminate is the final point of no return of a coroutine. Note that the procedure body of a coroutine must not return and that coroutines can only terminate themselves.

Alternatively, if Disconnect is used instead of Terminate, the task is still considered terminated but the coroutine may be switched to again and/or assigned to a new task.

Current returns the current task and CurrentGroup the current task group.

Schedulers

The main task group consists only of the main task which represents the main coroutine (i.e. Coroutines.main). The scheduler of the main task group is NIL, i.e. Terminate causes program termination, Suspend returns immediately and Select, WaitForOneOf and WaitFor pass their condition set (condition resp.) to Conditions.WaitFor.

A scheduler (usually represented by a module) consists of three parts:

initialization (i.e. creation of a new task group),
setup (at least one task should be placed here in the new task group), and
the start of the scheduler.

Additionally, group members should be allowed to create new members. The procedure which represents the scheduler should return to the calling procedure if all members are terminated but should not terminate itself.

A new task group is to be initialized by InitGroup. Note that the allocation of tg is to be done in advance because most schedulers need an extension of TaskGroup. The current task becomes the scheduler of the new task group.

Init initializes a new task and associates it with a coroutine and a task group. The coroutine must have been created in advance but from the viewpoint of Tasks it does not matter whether the coroutine was already running or not. Init initializes the errors component of the task and calls RelatedEvents.QueueEvents for it. Task related errors errors should be related to the errors component instead to the task itself.

The task which represents the scheduler is free to select one of its group members and to dispatch it by a call to Dispatch. Dispatch returns code and, if code equals waitfor, the associated conditionSet:

terminate: requires the task to be removed from the group, i.e. the task must not be dispatched again.
suspend: the suspending task gratefully gives control to the scheduler in the hope to become active again.
waitfor: the suspending task waits for conditionSet.

Terminate, Suspend and Select determine the return values of Dispatch (code and conditionSet) and return to the scheduler of the current task group.

DIAGNOSTICS

Some of the possible errors lead to following error events:

taskGroupMismatch: an error which is generated by Dispatch if task and task group do not match.
dispatchTerminatedTask: is generated if Dispatch is called for a task which is already terminated.
wrongScheduler: is generated if the scheduler of the task passed to Dispatch is not the current task.
invalidSet: is raised if an empty condition set was passed to Select or WaitForOneOf.

These events are passed to RelatedEvents (and related to the task group) which (by default) passes them to Events where they are initially ignored. Error events are raised with priority Priorities.liberrors.

Ulm's Oberon Library: Tasks