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

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

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

which would suggest that theTime exception could be raised when there is a loss ofprecision 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.

val tick : time

The description of theTime.fromSecondsand related operations should be rewritten as follows:

These convert the number n to atimevalue denoting n seconds (respectively, milliseconds, microseconds, or nanoseconds).This conversion is truncated toward zero (as done byInt.quot) if necessary. Ifthe value is too large to be represented as aTime.time value, then the exceptionTime is raised.

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

• tick
  the smallest representable time quanta. Specifying avalue smaller than this usingfromNanoseconds (or similar function) will result inzeroTime.

There is a question of whattick should represent and if it should be a function orjust aTime.time value. Some possible choices are

• Havetick be aTime.time value that is the smallest time value representableas aTime.time value. This value is unrelated to the underlying operating-system'ssmallest time quanta.

• Havetick be aTime.time value that is the host system's smallest time quanta.The assumption is that the value is representable as aTime.time value. One concernis that an operating system might support configuring the time quanta so that thisvalue could be incorrect if a program is run on a different machine from where itwas compiled.

• Havetick be aunit -> Time.time function that returns the host system'ssmallest time quanta. This choice addresses the second issue with the previouschoice.

• Have the representation oftick be anIntInf.int number of nanoseconds, insteadof aTime.time value. This choice is compatible with the previous choices.An integer value may be more useful than aTime.time value.

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

This proposal follows existing practice in known SML implementations, so itshould not affect any existing code. Adding thetick value or function shouldnot break any code.

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

• [2024-11-18] Proposed