2024 001 Clarification of Time module operations

Proposal 2024-001

Clarification of Time Module Operations

Author: John Reppy and Skye Soss
Last revised: November 18, 2024
Status: proposed
Discussion: issue #35

---

Summary

The specification of the functions that create time values from numbers of seconds, etc. is not clear about when the Time exception should be raised. Specifically, it states

These convert the number n to a time value denoting n seconds (respectively, milliseconds, microseconds, or nanoseconds). If the result is not representable by the time type, then the exception Time is raised.

which would suggest that the Time exception could be raised when there is a loss of precision in the result.

This proposal clarifies the intended semantics for these operations and, in addition, adds a function for determining the precision supported by time values.

Synopsis

val tick : time

Description

The description of the Time.fromSeconds and related operations should be rewritten as follows:

These convert the number n to a time value denoting n seconds (respectively, milliseconds, microseconds, or nanoseconds). This conversion is truncated toward zero (as done by Int.quot) if necessary. If the value is too large to be represented as a Time.time value, then the exception Time is raised.

In addition, we add the tick value (see the discussion for alternatives) with the following description:

• tick
  the smallest representable time quanta. Specifying a value smaller than this using fromNanoseconds (or similar function) will result in zeroTime.

Discussion

There is a question of what tick should represent and if it should be a function or just a Time.time value. Some possible choices are

• Have tick be a Time.time value that is the smallest time value representable as a Time.time value. This value is unrelated to the underlying operating-system's smallest time quanta.

• Have tick be a Time.time value that is the host system's smallest time quanta. The assumption is that the value is representable as a Time.time value. One concern is that an operating system might support configuring the time quanta so that this value could be incorrect if a program is run on a different machine from where it was compiled.

• Have tick be a unit -> Time.time function that returns the host system's smallest time quanta. This choice addresses the second issue with the previous choice.

• Have the representation of tick be an IntInf.int number of nanoseconds, instead of a Time.time value. This choice is compatible with the previous choices. An integer value may be more useful than a Time.time value.

We are currently proposing the first choice, but one of the others might be better.

Impact

This proposal follows existing practice in known SML implementations, so it should not affect any existing code. Adding the tick value or function should not break any code.

Rationale

This proposal makes explicit the ordering of effects for these functions, which will improve consistency across implementations.

---

History

• [2024-11-18] Proposed

---