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


Ulm's Oberon Library:
Clocks


NAME

Clocks - general interface for clocks and timers

SYNOPSIS

TYPE Clock = POINTER TO ClockRec;
TYPE ClockRec = RECORD (Services.ObjectRec) END;
CONST settime = 0; timer = 1; passed = 2;
TYPE CapabilitySet = SET; (* OF [settime..passed] *)
TYPE GetTimeProc = PROCEDURE (clock: Clock; VAR time: Times.Time);
TYPE SetTimeProc = PROCEDURE (clock: Clock; time: Times.Time);
TYPE PassedProc = PROCEDURE (clock: Clock; time: Times.Time) : BOOLEAN;
TYPE TimerOnProc = PROCEDURE (clock: Clock; time: Times.Time;
                              event: Events.Event);
TYPE TimerOffProc = PROCEDURE (clock: Clock);
TYPE GetPriorityProc = PROCEDURE (clock: Clock;
                                  VAR priority: Priorities.Priority);
TYPE Interface = POINTER TO InterfaceRec;
TYPE InterfaceRec =
   RECORD
      (Objects.ObjectRec)
      gettime: GetTimeProc;
      settime: SetTimeProc;
      passed: PassedProc;
      timeron: TimerOnProc;
      timeroff: TimerOffProc;
      getpriority: GetPriorityProc;
   END;


VAR system: Clock; (* the clock of the operating system *)

CONST cannotSetTime = 0; (* SetTime not implemented *) CONST cannotSetTimer = 1; (* timer not implemented *) CONST errorcodes = 2; TYPE ErrorEvent = POINTER TO ErrorEventRec; TYPE ErrorEventRec = RECORD (Events.EventRec) errorcode: SHORTINT; END; VAR errormsg: ARRAY errorcodes OF Events.Message; VAR error: Events.EventType;

PROCEDURE Init(clock: Clock; if: Interface; caps: CapabilitySet); PROCEDURE Capabilities(clock: Clock) : CapabilitySet; PROCEDURE CreateStaticClock(VAR clock: Clock); PROCEDURE GetTime(clock: Clock; VAR time: Times.Time); PROCEDURE SetTime(clock: Clock; time: Times.Time); PROCEDURE Passed(clock: Clock; time: Times.Time) : BOOLEAN; PROCEDURE TimerOn(clock: Clock; time: Times.Time; event: Events.Event); PROCEDURE TimerOff(clock: Clock); PROCEDURE GetPriority(clock: Clock; VAR priority: Priorities.Priority);

DESCRIPTION

Clocks provides an interface for clocks and associated timers. A clock is a source which returns a current time.

Init initializes a newly created clock and associates it with the given interface if and caps. The interface procedures are expected to meet the specifications following:

gettime: PROCEDURE(clock: Clock; VAR time: Times.Time);
return the current time.

settime: PROCEDURE(clock: Clock; time: Times.Time);
set the current time to time. This procedure needs only to be provided if settime is given in the set of capabilities.

passed: PROCEDURE(clock: Clock; time: Times.Time) : BOOLEAN;
returns TRUE if time has already passed. This procedure is optional and needs only to be provided if passed is given in the set of capabilities. This interface procedure allows to reduce the number of gettime invocations if the last time returned by gettime is compared first against time before the current time is considered. This is useful if invocations of gettime are more expensive than ordinary procedure calls.

timeron: PROCEDURE(clock: Clock; time: Times.Time; event: Events.Event);
cause event to be raised if the given time is reached. Only one alarm time and one event has to be maintained. New settings override older calls to timeron if timeron is called multiple times. timeron is expected to raise event immediately if time lies in the past. This procedure needs only to be provided if timer is given in the set of capabilities.

timeroff: PROCEDURE(clock: Clock);
switch off the timer.

getpriority: PROCEDURE(clock: Clock; VAR priority: Priorities.Priority);
return the priority of the timer. This is defined to be the minimal priority during the processing of events passed to timeron. Priorities.base is to be returned if there is no minimal priority (e.g. for static clocks).

Capabilities returns the set of capabilities of clock. Note that Passed can be called in any case whether passed is set or not.

CreateStaticClock creates and initializes a static clock. Static clocks return the last time setting of SetTime.

GetTime returns the current time of clock. SetTime sets the current time of clock to time. Passed returns TRUE if time has already been passed.

TimerOn causes clock to raise event if time is reached. Multiple calls override previous settings. TimerOff switches off the timer. GetPriority returns the priority of the associated timer. This is the minimal priority when events which has been passed to TimerOn are raised.

Clocks exports system which is expected to be initialized by a system dependent module to represent the clock of the operating system. Initially, system is initialized as a static clock.

DIAGNOSTICS

Errors lead to events which are passed to RelatedEvents and related to the clock. By default, error events are queued. Following error codes are implemented:
cannotSetTime
SetTime is not implemented for the given clock.
cannotSetTimer
The given clock does not support a timer.

An assertion of Init fails if the given clock has not been initialized by Services.Init. Various assertions that verify that all required interface procedures passed to Init are non-NIL.

SEE ALSO

Events
event handling
RelatedEvents
handling of error events
Services
definition of type-independent extensions
TimeConditions
conditions which allow to wait for a given time
Times
representations of time values
UnixClock
reinitializes system (if imported)

Edited by: borchert, last change: 2004/04/23, revision: 1.8, converted to HTML: 2004/04/23

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