To: J3                                                     J3/21-117r1
From: Richard Bleikamp & JoR & John Reid
Subject: system_clock() with normative changes
Date: 2021-February-23

Reference: 21-104r2

This r1 paper changes one sentence in the edits [437:16], replacing
(in the 2nd paragraph)
  "should all use the same type and kind type parameters for all
   arguments,"
with
  "should all use the same kind type parameter for all integer
   arguments,"


This paper is an alternative to 21-104r1.  21-104r1 introduces a NOTE
that describes best practice for calling system_clock().  This
papers add edits that prohibit some very poor practices, and adds
further emphasis about how the kind of integers passed to system_clock
should always be consistant across all calls to system_clock(), if
the values returned are used to compute elasped time.

EDITS: against 21-007

[437:5]
  replace "shall be an integer scalar"
  with "shall be an integer scalar with a decimal exponent range
        equal to or greater than RANGE(0)."

[437:10]
  After "shall be an integer or real scalar." add the sentence,
  "If COUNT_RATE is of type integer, it shall have a decimal exponent
   range equal to or greater than RANGE(0)."

[437:13]
  replace "shall be an integer scalar"
  with "shall be an integer scalar with a decimal exponent range
        equal to or greater than RANGE(0)."

[437:14+] add this paragraph
  "In an invocation of SYSTEM_CLOCK, all arguments of type integer shall
   have the same kind type parameter."

[437:15] replace
    "a single clock"
  with
    "one or more clocks of its own"

[437:16] Add, after the period,
    "A processor is allowed to scale the clock rate based on the type
     and kind type parameters of the arguments to SYSTEM_CLOCK.

     When an image has more than one clock, or the processor scales
     a clock's rate based on the type or kind type parameter of the
     arguments to SYSTEM_CLOCK, different invocations of SYSTEM_CLOCK
     should all use the same kind type parameter for all integer
     arguments, to ensure any timing calculations based on the COUNT
     and COUNT_RATE returned from those invocations use the same clock
     and clock rate.  When only the COUNT_RATE argument is present in an
     invocation of SYSTEM_CLOCK, and it is of type real, which clock or
     scaled clock rate used is processor dependent."

[437,21+], add this NOTE
NOTE
  "Many systems have a clock that is too fast to be effectively
  supported with default integers. Therefore, it is recommended that all
  invocations of SYSTEM_CLOCK use integer arguments with a decimal
  exponent range of at least 18.

  Using SYSTEM_CLOCK in this manner may minimize how often the
  returned COUNT "rolls over" and the processor will typically select
  the most accurate clock available."

---- end of edits