See:
          Description

Clocks and Timers

This section describes the RTSJ clocks and timers. These classes:

• Allow creation of a timer whose expiration is either periodic or set to occur at a particular time as kept by a system-dependent time base (clock).
• Trigger some behavior to occur on expiration of a timer, using the asynchronous event mechanisms provided by the specification.

Definitions

A timing mechanism is either a Clock or a Timer, capable of representing and following the progress of time, by means of time values.

A monotonic clock is a clock whose time values are monotonic, and a monotonic non-decreasing clock is a clock whose time values are monotonic non-decreasing. Monotonicity is a boolean property, while time synchronization, uniformity and accuracy are characteristics that depend on agreed tolerances.

Time synchronization is a relation between two clocks. Two clocks are synchronized when the difference between their time values is less than some specified offset. Synchronization in general degrades with time, and may be lost, given a specified offset.

Resolution is the minimal time value interval that can be distinguished by a timing mechanism.

Uniformity, in this context, refers to the measurement of the progress of time at a consistent rate, with a tolerance on the variability. Uniformity is affected by two other factors, jitter and stability.

Jitter is a short-term and non-cumulative small variation caused by noise sources, like thermal noise. More practically, jitter refers to the distribution of the differences between when events are actually fired or noticed by the software and when they should have really occurred according to time in the real-world.

(Lack-of) stability accounts for large and often cumulative variations, due to e.g. supply voltage and temperature.

In practice a timing mechanism is driven by an oscillator. Accuracy is the difference between the desired frequency and the actual frequency of the oscillator, and a major reason of synchronization loss.

The system real-time clock is monotonic non-decreasing, with the epoch as the Epoch (January 1, 1970, 00:00:00 GMT). The system real-time clock is not necessarily synchronized with the external world, and the correctness of the epoch as a time base depends on such synchronization. It is as uniform and accurate as allowed by the underlying hardware.

A Timer measures time using a given Clock, and fires an event as scheduled.

In the context of a Timer, firing is the action that causes the release of any associated AsyncEventHandler, while the skipping of firing is an action with no consequences.

A Timer is active if it has been started and not stopped since last started and it has a time in the future at which it is expected to fire or skip, else it is not-active.

In the context of a Timer, enabling allows firing, while disabling causes the skipping of firing. Enabling and disabling act as a mask over firing.

The behavior of a OneShotTimer is that of a Timer that does not automatically reschedule its firing after an initial firing, or after the skipping of an initial firing (if disabled and active when the firing was due). It is specified using an initial firing time.

The behavior of a PeriodicTimer is that of a Timer that automatically reschedules its firing after an initial firing, or after the skipping of an initial firing if disabled when the firing was due. It is specified using an initial firing time and an interval or period used for the self-rescheduling.

Every timer has at least one clock associated with it, on which the measurement of time will be based. The OneShotTimer timer has one, the clock associated with the specification of the initial firing time. The PeriodicTimer timer has two, the clock associated with the specification of the initial firing time and the clock associated with the specification of the interval or period.

Overview

The classes provided by this section are Clock, Timer, PeriodicTimer, and OneShotTimer.

At least one instance of the abstract Clock class is provided by the implementation, the system real-time clock, and this instance is made available as a singleton.

Timer is an abstract class and consequently only its subclasses can be instantiated. The Timer class provides the interface and underlying implementation for both one-shot and periodic timers.

Instances of OneShotTimer and PeriodicTimer can be created and rescheduled specifying the initial firing time either as an AbsoluteTime, to be considered at the application of the start command, or as a RelativeTime, to be considered from the application of the start command.

The period for a PeriodicTimer is always specified as a RelativeTime.

An instance of OneShotTimer describes an event that is to be triggered at most once (unless restarted after expiration). It may be used as the source for time-outs.

An instance of PeriodicTimer fires or skips on a periodic schedule.

Semantics and Requirements

This list establishes the semantics and requirements that are applicable across the classes of this section. Semantics that apply to particular classes, constructors, methods, and fields will be found in the class description and the constructor, method, and field detail sections.

1. Clocks and Timers relation:
   1. The relation between clocks and timers described below is better understood if a clock is seen as providing an interrupt at intervals based on its resolution.
   2. Timers can be modeled as counters, or as comparators.
   1. Timer modeled as counter: The timer is viewed as if every clock interrupt increments a count up to the firing count, initially given by either an instance of RelativeTime or computed as the difference between an instance of AbsoluteTime and a semantically specified "now" (using the same clock).
      • In this model, start is understood as defining "now" and start counting, stop is understood as stop counting. start after stop may be understood as start counting again from where stopped, or start from scratch after resetting the count. In both cases a delay is introduced.
      • An RTSJ Timer, when using the counter model, resets the count when it is re-started after being stopped.
   2. Timer modeled as comparator: The timer is viewed as if every clock interrupt forces a comparison between an absolute time and a firing time, initially given either as an instance of AbsoluteTime or computed as the sum of an instance of RelativeTime and a semantically specified "now" (using the same clock).
      • In this model, start is understood as start comparing, and possibly the first start is understood as defining "now". stop is understood as stop comparing. start after stop may be understood as start comparing again. In this case no delay is introduced.
   3. When a Timer is created or rescheduled using a RelativeTime to specify the initial firing time, the RTSJ keeps the specified initial firing time as a RelativeTime and behaves according to the counter model.
   4. When a Timer is created or rescheduled using an AbsoluteTime to specify the initial firing time, the RTSJ keeps the specified initial firing time as an AbsoluteTime and uses the comparator model.
2. The Clock class shall be capable of reporting the achievable resolution of timers based on that clock.
3. The OneShotTimer class shall ensure that a one-shot timer is triggered at most once unless restarted after expiration.
4. The PeriodicTimer class shall allow the period of the timer to be expressed in terms of a RelativeTime or a RationalTime (now deprecated).
5. The initial firing, or skipping, of a PeriodicTimer occurs in response to the invocation of its start method, in accordance with the start time passed to its constructor. This initial firing, or skipping, may be rescheduled by a call to the reschedule method, in accordance with the time passed to that method.
6. For a PeriodicTimer:
   1. Let S be the absolute time at which the initial firing or skipping of a PeriodicTimer is scheduled to occur:
      1. If the start, or reschedule, time was given as an absolute time, A, and that time is in the future when the timer is made active, then S equals A. Otherwise, if the absolute time has passed when the timer is made active, then S equals the time at which the timer was made active.
      2. If the start, or reschedule, time was given as a relative time, R, then S equals the time at which the counting time, started when the timer was made active, equals R.
         NOTE: The transition to not-active by this timer causes the counting time to reset, effectively preventing this kind of timer from firing immediately, unless given a time value of 0.
   2. The firings, or skippings, of a PeriodicTimer are scheduled to occur according to S+nT, for n = 0, 1, 2 ..., where S is as just specified, and T is the interval of the periodic timer.
7. When in a not-active state a Timer retains the parameters given at construction time or the parameters it had at de-activation time. Those are the parameters that will be used upon invocation of start while in that state, unless the parameters are explicitly changed before that, using reschedule and setInterval as appropriate.
8. If a Timer object is allocated in a scoped memory area, then it will increment the reference count associated with that area. Such a reference count will only be decremented when the Timer object is destroyed. (See semantics in the Memory chapter for details.)
9. A Timer object will not fire before its due time.

Rationale

Clocks differ because of monotonicity, synchronization, jitter, stability, accuracy, and resolution. There are many possible subclasses of clocks: real-time clocks, user time clocks, simulation time clocks, wall clocks.

The idea of using multiple clocks may at first seem unusual but it is allowed to accommodate differences and as a possible resource allocation strategy. Consider a real-time system where the natural events of the system have different tolerances for jitter. Assume the system functions properly if event A is fired within plus or minus 100 seconds of the actual time it should occur but event B must be fired within 100 microseconds of its actual time. Further assume, without loss of generality, that events A and B are periodic. An application could then create two instances of PeriodicTimer based on two clocks. The timer for event B should be based on a Clock which checks its queue at least every 100 microseconds but the timer for event A could be based on a Clock that checked its queue only every 100 seconds. This use of two clocks reduces the queue size of the accurate clock and thus queue management overhead is reduced.

The importance of the use of one-shot timers for time-out behavior and the vagaries in the execution of code prior to starting the timer for short time-outs dictate that the triggering of the timer should be guaranteed. The problem is exacerbated for periodic timers where the importance of the periodic triggering outweighs the precision of the start time. In such cases, it is also convenient to allow, for example, a relative time of zero to be used as the start time.