1

[This clause specifies a high-resolution, monotonic
clock package.]

2

The following language-defined
library package exists:

3

4

Time_First :

Time_Last :

Time_Unit :

5

Time_Span_First :

Time_Span_Last :

Time_Span_Zero :

Time_Span_Unit :

6

7

8

9

10

11/1

12

13

14/2

{*AI95-00386-01*}
**function** Nanoseconds (NS : Integer) **return** Time_Span;

**function** Microseconds (US : Integer) **return** Time_Span;

**function** Milliseconds (MS : Integer) **return** Time_Span;

**function** Seconds (S : Integer) **return** Time_Span;

**function** Minutes (M : Integer) **return** Time_Span;

15

16

17

... --

17.a/2

18

In this Annex, *real time*
is defined to be the physical time as observed in the external environment.
The type Time is a *time type* as defined by 9.6;
[values of this type may be used in a delay_until_statement.]
Values of this type represent segments of an ideal time line. The set
of values of the type Time corresponds one-to-one with an implementation-defined
range of mathematical integers.

18.a

18.b

19

The Time
value I represents the half-open real time interval that starts with
E+I*Time_Unit and is limited by E+(I+1)*Time_Unit, where Time_Unit is
an implementation-defined real number and E is an unspecified origin
point, the *epoch*, that is the same for all values of the type
Time. It is not specified by the language whether the time values are
synchronized with any standard time reference. [For example, E can correspond
to the time of system initialization or it can correspond to the epoch
of some time standard.]

19.a

19.b

This half-open interval I consists of all real
numbers R such that E+I*Time_Unit <= R < E+(I+1)*Time_Unit.

20

Values of the type Time_Span represent length of
real time duration. The set of values of this type corresponds one-to-one
with an implementation-defined range of mathematical integers. The Time_Span
value corresponding to the integer I represents the real-time duration
I*Time_Unit.

20.a

20.b

21

Time_First and Time_Last are the smallest and largest
values of the Time type, respectively. Similarly, Time_Span_First and
Time_Span_Last are the smallest and largest values of the Time_Span type,
respectively.

22

A value of type Seconds_Count represents an elapsed
time, measured in seconds, since the epoch.

23

Time_Unit is the smallest amount of real time representable
by the Time type; it is expressed in seconds. Time_Span_Unit is the difference
between two successive values of the Time type. It is also the smallest
positive value of type Time_Span. Time_Unit and Time_Span_Unit represent
the same real time duration. A *clock tick*
is a real time interval during which the clock value (as observed by
calling the Clock function) remains constant. Tick is the average length
of such intervals.

24/2

{*AI95-00432-01*}
The function To_Duration converts the value TS to a value of type Duration.
Similarly, the function To_Time_Span converts the value D to a value
of type Time_Span. For To_Duration both
operations, the result is rounded to the nearest value
of type Duration exactly representable value
(away from zero if exactly halfway between two exactly
representable values). If the result is
outside the range of Duration, Constraint_Error is raised. For To_Time_Span,
the value of D is first rounded to the nearest integral multiple of Time_Unit,
away from zero if exactly halfway between two multiples. If the rounded
value is outside the range of Time_Span, Constraint_Error is raised.
Otherwise, the value is converted to the type Time_Span.

25

To_Duration(Time_Span_Zero) returns 0.0, and To_Time_Span(0.0)
returns Time_Span_Zero.

26/2

{*AI95-00386-01*}
{*AI95-00432-01*}
The functions Nanoseconds, Microseconds, and Milliseconds,
Seconds, and Minutes convert the input parameter to a value of
the type Time_Span. NS, US, and MS,
S, and M are interpreted as a number of nanoseconds, microseconds, and milliseconds, seconds, and minutes
respectively. The input parameter is first converted
to seconds and rounded to the nearest integral multiple of Time_Unit,
The result is rounded to the nearest exactly
representable value (away from zero if exactly halfway between
two multiples. If the rounded value is outside
the range of Time_Span, Constraint_Error is raised. Otherwise, the rounded
value is converted to the type Time_Span exactly
representable values).

26.a/2

27

The effects of the operators on Time and Time_Span
are as for the operators defined for integer types.

27.a

28

The function Clock returns the amount of time since
the epoch.

29

The effects of the Split and Time_Of operations are
defined as follows, treating values of type Time, Time_Span, and Seconds_Count
as mathematical integers. The effect of Split(T,SC,TS) is to set SC and
TS to values such that T*Time_Unit = SC*1.0 + TS*Time_Unit, and 0.0 <=
TS*Time_Unit < 1.0. The value returned by Time_Of(SC,TS) is the value
T such that T*Time_Unit = SC*1.0 + TS*Time_Unit.

30

The range of Time values shall be sufficient to uniquely
represent the range of real times from program start-up to 50 years later.
Tick shall be no greater than 1 millisecond. Time_Unit shall be less
than or equal to 20 microseconds.

30.a

31

Time_Span_First shall be no greater than –3600
seconds, and Time_Span_Last shall be no less than 3600 seconds.

31.a

32

A *clock jump* is the difference
between two successive distinct values of the clock (as observed by calling
the Clock function). There shall be no backward clock jumps.

33

The implementation shall document the values of Time_First,
Time_Last, Time_Span_First, Time_Span_Last, Time_Span_Unit, and Tick.

33.a/2

34

The implementation shall document the properties
of the underlying time base used for the clock and for type Time, such
as the range of values supported and any relevant aspects of the underlying
hardware or operating system facilities used.

34.a.1/2

34.a

35

The implementation shall document whether or not
there is any synchronization with external time references, and if such
synchronization exists, the sources of synchronization information, the
frequency of synchronization, and the synchronization method applied.

35.a.1/2

36/1

The implementation shall document any aspects of
the the external environment that could
interfere with the clock behavior as defined in this clause.

36.a.1/2

36.a

37

For the purpose of the metrics defined in this clause,
real time is defined to be the International Atomic Time (TAI).

38

The implementation
shall document the following metrics:

39

An upper bound on the real-time duration of a clock
tick. This is a value D such that if t1 and t2 are any real times such
that t1 < t2 and Clock_{t1}
= Clock_{t2}
then t2 – t1 <= D.

40

An upper bound on the size of a clock jump.

41

An upper bound on the *drift
rate* of Clock with respect to real time. This is a real number D
such that

42

E*(1–D) <= (Clock_{t+E} – Clock_{t}) <= E*(1+D)

provided that: Clock_{t} + E*(1+D) <= Time_Last.

provided that: Clock

43

where Clock_{t}
is the value of Clock at time t, and E is a real time duration not less
than 24 hours. The value of E used for this metric shall be reported.

43.a

44

An upper bound on the execution time of a call
to the Clock function, in processor clock cycles.

45

Upper bounds on the execution times of the operators
of the types Time and Time_Span, in processor clock cycles.

45.a

45.a.1/2

46

Implementations targeted to machines with word size
smaller than 32 bits need not support the full range and granularity
of the Time and Time_Span types.

46.a

46.b

Since the range and granularity are implementation
defined, the supported values need to be documented.

47

When appropriate, implementations should provide
configuration mechanisms to change the value of Tick.

47.a.1/2

47.a

47.b

47.c

48

It is recommended that Calendar.Clock and Real_Time.Clock
be implemented as transformations of the same time base.

48.a.1/2

49

It is recommended that the “best” time
base which exists in the underlying system be available to the application
through Clock. “Best” may mean highest accuracy or largest
range.

49.a.1/2

NOTES

50

38 The rules in this clause do not imply
that the implementation can protect the user from operator or installation
errors which could result in the clock being set incorrectly.

51

39 Time_Unit is the granularity of the
Time type. In contrast, Tick represents the granularity of Real_Time.Clock.
There is no requirement that these be the same.

51.a/2

{*AI95-00386-01*}
Functions Seconds and Minutes
are newly added to Real_Time. If Real_Time is referenced in a use_clause,
and an entity *E* with a defining_identifier
of Seconds or Minutes is defined in a package that is also referenced
in a use_clause,
the entity *E* may no longer be use-visible, resulting in errors.
This should be rare and is easily fixed if it does occur.

51.b/2

{*AI95-00432-01*}
Added wording explaining how and when many of these
functions can raise Constraint_Error. While there always was an intent
to raise Constraint_Error if the values did not fit, there never was
any wording to that effect, and since Time_Span was a private type, the
normal numeric type rules do not apply to it.

Ada 2005 and 2012 Editions sponsored in part by **Ada-Europe**