The lunar clock has a new name: rtaps which stands for [R]PC [T]imestamp [A]djustment [P]rogram [S]erver. Yeah, I know, a bit contrived, but aren't all acronyms?

The code has now been published on GitHub at https://github.com/stroggprog/rtap and can be cloned using git or downloaded as a compressed zip archive.

I have decided not to turn the program into an NTP server, since that is non-trivial task. If someone thinks that would be a great idea (I no longer think so), they can take existing NTP code and amend it.

When a program requests the time from the system clock, what it is actually doing is requesting a timestamp that is valid at the moment when the timestamp is 'snapped'. By the time it reaches the requesting program, it is already out of date, or should at least be considered so. Generally, this isn't a big problem, but when requesting a timestamp with nanosecond granularity, it definitely is. Hence we need to think in terms of timestamps, not 'current time'.

The rtaps program will do one of two things: If it is provided with a timestamp, it will adjust it to counter the effects of relativity. If it isn't provided with a timestamp, it will request one from the system clock and adjust it.

At the moment, these two functionalities are provided through separate RPC functions, so there is no doubt about what happens when a program makes a call. Think of it as a way of managing expectations.

There is also a function available through the RPC interface to set the moment from which relativistic effects should be countered. For example, if the timekeeper (which may be the clock on the same machine as rtaps, or another server which provides NTP services) is retrained to be synchronous with UTC as it is experienced here on Earth, the time when this occurred needs to be recorded so only time after that moment is adjusted. That moment is called the private epoch. Calling the function SetPrvEpoch with a timestamp will set the private epoch to that time and write the time to the rtaps configuration file (in case of a restart).

As mentioned above, there is a configuration file. When the program is first run it will look for it, and if not found it will create it with sensible default values. If the configuration file is manually edited, the program will need to be restarted to load the new values. The only exception is the private epoch, which if changed via the SetPrvEpoch call will come into effect immediately.

For this part of the discussion, image we are on Earth's moon.

If there is an experiment that is going to timestamp the results (or the data it has just collected), it grabs a timestamp from its own system clock. This clock has drifted from Earth-UTC due to relativistic effects as a result of the lower gravity. It sends that timestamp to the RPC server which adjusts it so it now represents the same moment in Earth-UTC.

Since there is a processing delay while the RPC server adjusts the timestamp, the RPC server cannot be used as a clock with a granularity less than a microsecond. A program that represents a clock (e.g. displaying the time and updating in real-time) must take this into consideration. However, it can make its own adjustments if it notes the turnaround time between requesting the adjusted time and receiving it - but the process of applying the secondary adjustment of the turnaround time is also time expensive. Nonetheless, noting the average turnaround time will reveal how accurate the displayed clock is. If it takes an average of 150 microseconds to receive the timestamp from the RPC server, the clock cannot be relied on to be more accurate than this (and since this is an average, arguably it is less accurate than this). Therefore, in this case, the clock should not display greater granularity than thousandths of a second - which is fine for most clocks which only wish to display seconds with an update of approximately ten times per second.