2nd attempt to close issue 3881

[arkiuat]

I've attempted to implement the changes that @librasteve suggested in problem-solving issue 497 with the modifications that I suggested and he okayed in #3881 .

I've also updated the dates in the examples where they can be updated, and added a brief explanation at the very end as to why the "future leap seconds" examples have to be so very old (for now).

Finally I've tried to reign in some of my immoderate language a bit. I hope that this proves acceptable and that we can close the docs issue that spawned it.

[librasteve]

This is great - all looks good to me.

Thanks for persevering with this against all odds.

[arkiuat]

I was looking back over the issue, and @0rir made some excellent remarks about using links to wikipedia articles, and possibly adding a glossary entry or two to link to. Specifically I think I'd like to link to some or all of the following wikipedia articles (shown with intended linktext): timescale, POSIX time, UTC, TAI

Linking directly to these articles where relevant might be sufficient so we might not need any new glossary entries.

I need to think this over a bit but I plan to add a few more edits to this PR before merging.

[raiph]

Hi @arkiuat

I'm not especially confident using git / github, so I feel unsure whether you read my comment about the use of the word "track" in "The numerical value of Instant happens to track atomic-clock time".

I'd be comforted if you could note here whether you understood the essence of what I was pointing out, given that it's pretty fundamental to the difference between Instants and atomic-clock time, and the skew or even negative difference between one instant and another (usually significant; frequently many milliseconds; often several seconds on Windows machines; even hours or days if one is unlucky), and thus the knock-on consequences for Duration.

[arkiuat]

I feel unsure whether you read my comment about the use of the word "track" in "The numerical value of Instant happens to track atomic-clock time".

Hi @raiph: I have not seen it. I've looked in several places, and cannot find it. I would be very interested to read it.

[raiph]

@arkiuat

Here's what I wrote:

The numerical value of Instant happens to track atomic-clock time

The word "tracks" is... interesting. I may well have misunderstood the context, and thus whether that's a reasonable thing to write, but it sounds... potentially significantly misleading.

What do you intend the word "tracks" to imply, and is it reasonable to think the reader will correctly infer what they need to infer?

I posed a question to google's gemini about a mythical PL's Instant datatype, in respect of whether it would "track" atomic time, and a couple other details, without mentioning Raku. This was its answer:

An "[Instant]" (like Java's java.time.Instant or similar in other languages) represents a specific point on a linear, UTC-based timeline. It is typically initialized from the system's Real-Time Clock (RTC), which, despite using crystal oscillators that can drift by seconds daily, is corrected by periodic Network Time Protocol (NTP) updates, generally keeping devices synchronized within milliseconds to seconds of atomic-clock time.

Here is a breakdown of the accuracy and behaviors you described:

• What is an Instant? It is an absolute moment, often recorded as seconds and nanoseconds since the Unix Epoch (1970-01-01T00:00:00Z). It ignores time zones and daylight saving time, representing UTC time.

• System Clock Drift: You are correct that local hardware clocks (crystal-based) drift. Without synchronization, they can easily drift several seconds per day.

• NTP Synchronization: NTP corrects this by communicating with time servers (often stratum 1 or 2, which are connected to atomic clocks) to adjust the local system time. Unix/Linux: Often uses ntpd or chronyd, which can check for updates every 17 minutes by default, but it’s adjustable. Apple Devices: Apple frequently uses their own timed daemon, which is designed to be aggressive with syncs to maintain high accuracy. Windows: The default Windows Time service (W32Time) sync interval is much less frequent, historically defaulting to once a week, though it can be adjusted.

• Precision and Accuracy: While an Instant may provide nanosecond or microsecond precision in code, the accuracy relative to a real-world atomic clock is limited by network latency and the frequency of NTP adjustments.

Important Nuances:

• Leap Seconds The Instant type in many languages (especially Java/Unix time) traditionally excludes leap seconds, meaning it tracks a linear, continuous time rather than exact Coordinated Universal Time (UTC).

• Clock Jumps: When NTP corrections are large, the system clock might jump backward or forward. High-accuracy systems use monotonic clocks (e.g., CLOCK_MONOTONIC) for measuring durations, not the "Instant" of the day.

To summarize why I'm writing this comment, I want to make sure folk are taking into account that, unless Instants are some special thing that I don't currently think they are, a new one will typically be adrift from atomic clock time from the getgo, and its drift from the atomic clock will drift further from the atomic clock as time passes, and two Instants will be adrift by differing amounts from each other, and that difference is likely significant if one cares about accuracy.

One upshot is that a Duration is much more approximate than one might naively expect, and, furthermore, may even be negative.

Joelle Maslak created and uploaded a Raku library. Reading its doc I get the impression it's a suitable alternative to using the built-in Instant/Duration for those who want much better anti-drift stability and/or monotonicity than the built-in Instant provides (as far as I know).

As usual, I may have gotten some of this wrong, or be out of date with what Rakoons have been up to, etc.

[arkiuat]

@raiph, thanks, this is a pretty good point about "track" being misleading when used in this context. I've used the web editor to change the statement that Instant "happens to track" TAI to now state merely that it "follows"