Seconds() and Uptime()

Wiki
1

Based on the discussion in What is the Difference Between the SECONDS() and UPTIME() Functions?...

I propose updating those two pages with Peter's explanations of the difference and suggested usage, with appropriate cross references.

Because this is explanations and usage, rather than simple typos, I'll post drafts here in a few days for a brief review cycle.

2 Likes
2

Here are my suggested updates to these two functions' Wiki pages. Please use the links in the function titles to see the current Wiki version.

I'm making up a graphic section division marker because the horizontal rule:

is nearly invisible.

.

SECONDS()

SECONDS Function

The SECONDS() function returns the time in fractional seconds, starting
at an arbitrary point.

The SECONDS() function returns CACurrentMediaTime() (give or take a microsecond), which is part of Apple's "Core Animation" API group. According to Apple developer documentation, it "Returns the current absolute time, in seconds." and is based on mach_absolute_time(), which, also according to Apple developer documentation, "Returns the current value of a clock that increments monotonically in tick units (starting at an arbitrary point). This clock does not increment while the system is asleep."

Please don't mistake the term "absolute time" for universal clock time like that provided by the TIME Function or the ICU Date/Time Tokens. You should use SECONDS() if you want to keep track of time differences for short periods (such as how long a macro takes to execute).

See Also

Functions

Forum

UPTIME()

UPTIME Function

The UPTIME() function returns the time in fractional seconds that the Mac has been awake since it booted.

The UPTIME() function returns NSProcessInfo.processInfo.systemUptime. According to Apple developer documentation, "The amount of time the system has been awake since the last time it was restarted."

Use UPTIME() for the time (accurate to a few milliseconds) since the Mac was rebooted. Use SECONDS() if you want to keep track of time differences for short periods (such as timing how long a macro takes to execute).

See Also

Functions

Forum

3

The details of the implementation should not really be documented so explicitly, because they could change in the future.

The wiki should document what it is and what it does. How it does it should only be noted in a minor way if at all.

So things SECONDS should document:

  • That it is fractional seconds
  • That is it highly precise (though ideally without specifying the precision (perhaps sub-millisecond).
  • That it starts at an arbitrary point and will keep counting up
  • That it may not count when the system is asleep so should not be used for long term comparisons
  • That it should be used for short term comparisons such as how long something takes to happen.

Things it should not document in any notable way (maybe in a tech section at the bottom):

  • That it is based CACurrentMediaTime that in turn is based on mach_absolute_time
  • Specifics of the Apple developer docs related to them

Same for UPTIME, document what it does and how to use it, but not how it does it or its precise accuracy.

Keyboard Maestro itself only executes actions at a rate of one per ms currently, so timing significantly below that is not likely to be useful since you couldn't use it fast enough to be relevant.