Author:         Harald Oehlmann <[email protected]>
State:          Draft
Type:           Project
Created:        21-May-2025
Tcl-Version:    9.1
Tcl-Branch:     1e2c6ce4-mswin-monotonic-clock
Keywords:       after

---

Abstract

This TIP proposes to change the time base for the after command from wall clock to a monotonic clock. It is currently limited on the Windows platform, as the issue of a jumping wall clock is common there.

Background

On the Windows platform, the wall clock may change at any time by:

*   manual time settings (time command in an administration shell)
*   suspension of the system
*   automatic setting of the time by the use of the NTP protocol, specially on day time switching (+/- 1 hour)

If the wall time is advanced by one hour, all after events within this hour will emideately fire. If the wall clock is turned back by one hour, all after events are delayed by one hour.

The consequences for my own applications are:

• any process with a time limit (like http::get -timeout 5000 sample.de) will time-out emideately without having reached the timeout
• any periodic procedure like a UI refresh will be delayed and causes a freeze of the UI, typically by one hour.

On Windows, there is a monotonic clock which does one tick per millisecond independent of the wall clock. If this clock is used for the after events, none of the upper problems arise. There is no other solution or work-around known for those issues.

In my application, the user may set the wall clock. But this is happening in another process due to the required administrative rights. The user process tries to prepare a whole set of after events, which may eventually fire after the set clock. This does not work, as a negative time may not be registered to after. So, if the clock is reversed by one hour, I need an after event at -59 minutes, what is currently not supported.

The original request is this Tk ticket 3328635 which is for Linux only. Tk ticket 1e2c6ce4 is for Windows platform.

Rationale

An after event based on the wall clock will be delayed or directly fired, if the wall clock changes. This is seen as a bug regarding the documentation.

The time command is also documented to work on a time interval. It is currently based on the wall clock what is seen as a bug.

The interpreter limit options are documented to be wall clock dependent, as they may change. This is not seen as a valid argument, as an interpreter should get a certain time, not a time point on the wall clock (which may change at any time). This is the only proposed change compared to the documentation.

TIP 233 functions Tcl_SetTimeProc/Tcl_QueryTimeProc are not documented. Not respecting them does not change the documentation.

Specification

The following changes are proposed:

• The after event is based on a monotonic clock
• The API described in TIP 233 (Tcl_SetTimeProc/Tcl_QueryTimeProc) is not used for this monotonic clock
• The time command should be based on a monotonic clock
• The interpreter limit should be based on a monotonic clock
• The proposal is only for the MS-Windows platform

Compatibility

In the moment when the wall clock is discontinuous, there is a big difference in compatibility, as the expected delay or direct firing is not happening any more.

Why Windows only?

I can not answer this question. We had many action here. On Linux it was seen as a breaking change which should not happen. I don't understand this.

There is an untested implementation for Linux and MacOS below. Nobody looked to it, so I am keeping it out of the TIP. If there is a supporter from other platforms, they may be added.

I go Windows only, as I know that, on this platform, this is a huge improvement which has no alternative. It is absolutely needed. Taking other platforms into account may cause discussions, which may withdraw this TIP.

Perhaps, other platforms don't have a jumping Wall clock and don't have the issue. I remember at my early times with Linux, that wall clock change was done by accellerating or delaying the clock and there is no discontinuation and specially no jump-back.

This is not the case on Windows. I know a huge industrial project which failed when the computer was changed from Linux to Windows and the system critical time-stamps started to jump back and it was not possible to avoid this on Windows. You may ask me verbally at the conference on this project.

Alternatives

Revert TIP 233

I would not mind to revert TIP233. There is no known usage and it is not documented. It is in the way of using a monotonic clock, thats all. I have no opinion here. I need the monotonic clock on Windows, thats all.

Support other platforms

No problem, sponsor it, test it, it depends on you ;-).

Great other ideas

There are many other great ideas around this subject, like "after -at 12:59:59". They are all great. Sergey has a great super-patch. This step is seen as a first step in this direction. Those great ideas are not taken into account to not delay this really urgent issue.

Other TCL versions

Of cause, this should be back-ported for all TCL versions, as it is always an issue. This is not proposed to not delay the TIP and to avoid discussions.

TIP 302

TIP 302 proposes the same issue. One may read the rationale there, which is more technical, as Kevin Kenny understands more of the backgrounds.

Discussion

Reference Implementation

A reference impementation can be found in Tcl branch 1e2c6ce4-mswin-monotonic-clock.

An untested patch for Linux and MacOS is found in Tcl branch tkt3328635-posix-monotonic-clock.

The great patch by Sergey: Ticket fdfbd5e10f

Credits

Thanks to Christian Werner and Sergey Brester for implementation and many work around this issue. Thanks to Kevin Kenny for maintaining the time part of TCL.

Copyright

This document has been placed in the public domain.