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

Reference: 21-104r1

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 type and kind type parameters for all
     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