Author: Harald Oehlmann <[email protected]>
State: Draft
Type: Project
Created: 21-May-2025
Tcl-Version: 9.1
Keywords: after
Abstract
This TIP proposes to add the timer ensemble to execute a command at a given wall clock point or after a given time period. In addition, the API functions of TIP 233 Tcl_SetTimeProc is not respected.
Rational
The current after command is used for two purposes, execute at a time delay and at a wall clock instant. This does not work, if time and wall clock differs, like on manual wall clock set, systen suspension etc. after was always documented to invoke at a time distance, but the implementation calculated the wall clock instance and executed at the wall clock instance. Androwish/Undroidwish and other alternate interpreters changed after to work on a monotonic clock since a long time.
For most use cases, like timeouts, gui refresh, periodic processes, the monotonic clock is the right time base. There are use cases for wall clock as a clock widget update.
Those two use cases should be split-up in two distinct commands.
TIP233 was implemented for simulaters within a NDC contract where usage is unknown. Its commands are not documented and current usage is unknown. It is supposed, that the after event should be simulated in a different time scale (probably slower) within simulators. If still usable, it has to be extended for monotonic clock. As no usage is known, its non respectence is proposed.
Specification
The new timer ensemble is proposed with the following subcommands:
timer in delay ?script ...?
The command will wait the given monotonic time, if no command given.
The command will be executed after the given delay in miliseconds following a monotonic clock if a command is given. A timer id is returned, which may be used to cancel the event.
timer at seconds ?milliseconds? ?script ...?
A wall clock time instance is specified as scands and optionally milliseconds (default to zero). The wall clock moment may be calculated as seconds+1000milliseconds*. milliseconds defaults to zero and may be any integer. The seconds parameter is typically returned by clock scan.
The command will wait until the given wall clock instance passed, if no command given.
The command will be executed at the given wall clock seconds, if a command is given. A timer id is returned, which may be used to cancel the event. TIP233 Tcl_SetTImeProc may be effective for this command.
timer cancel id
timer info ?id?
timer idle script ...
Those commands work the same way as in the after ensemble. They are interchangeable and will work on timer events started by the after ensemble and the timer ensemble. They exist twice to make scripts more consistent.
The after ensemble is not deprecated. Only the documentation of after delay cmd is updated to the implementation (e.g. time distance specified, but executed at wall clock instance).
The time command changes the time base to monotonic clock.
Compatibility
Fully backward compatible.
Discussion
Ashok observed from the Linux implementation by Christian, that there are linux system call limits set. If this is relevant to this TIP is unknown.
There is the proposal of a repetitve timer event. This is sensible but currently not covered. One step at a time.
Reference Implementation
There is a lot of work in this field, which may be used as a starting point. There is currently no 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.