SyncTimer - 1.2

timers synchronized with clock

Table Of Contents

NAME
SYNOPSIS
INTRODUCTION
CLOCK PRECISION and TUNING
EXAMPLE
NOTES
HISTORY

NAME

SyncTimer - timers synchronized with clock.

SYNOPSIS

package require SyncTimer

::SyncTimer::every interval basetime script ?script ...?

::SyncTimer::cancel id

INTRODUCTION

This package provides commands able to start/stop synchronized timers. Each time a timer is triggered, it executes a user-defined command. Timers are triggered at regular intervals, and are aligned (synchronized) with the system-clock.

i.e. timers can be triggered when the system-clock strikes the hours ( or the half-hours, or more ... read below)

::SyncTimer::every interval basetime script ?script ...?

This command creates and starts a new timer in sync with the system-clock.

interval is a specification of the interval; it should be expressed as a "relative time" (see [clock] command).

Example:

        "1 hour"
        "20 minutes"
        "2 minutes 30 seconds"

basetime is the time-displacement

Usually it is "00:00:00", meaning that timer should be aligned with system-clock. It can be any "relative time specification" (see [clock] command).

Example:
```
        ::SyncTimer::every "5 minutes" "00:00:10" ....
```
means that timer will be triggered every 5 minutes, 10 second after clock strikes the "5 minutes" ( i.e at hh:00:10, hh:05:10, hh:10:10, hh:15:10 ... hh:55:10)
Note that if you want timer be triggered 10 second *before* clock strikes the ""5 minutes", you should write
```
        ::SyncTimer::every "5 minutes" "00:04:50" ....        
```
( i.e at hh:04:50, hh:09:50, hh:14:50 ... hh:59:50)

: script ?script ...?
The triggered command is formed by concatenating all the script arguments in the same fashion as the concat command (see syntax for [after] command).

The SyncTimer::every command returns an identifier that can be used later to cancel the timer.

::SyncTimer::cancel id: This command stops the timer whose handler is id (id must be the return value from a previous SyncTimer::every command).

CLOCK PRECISION and TUNING

SyncTimer minimal resolution is 1 second.
SyncTimer is synchronized with the internal system-clock, with a precision of 1 millisec (Apart of delay due to the CPU scheduling).
Note that use of the "SyncTimer::clockTuning" variable is DEPRECATED.
- Statements like the following :
```
      set SyncTimer::clockTuning $newValue  ; # 0 <= newValue <= 999
```
  are supported for compatibility, but they have no effect.

EXAMPLE

Just a simple echo of current time, followed by a msg

   proc myCmd {msg} {
     puts -nonewline "[clock format [clock seconds] -format "%Y-%m-%d %T"]"
     puts " $msg"
   }
          
   set t1  [SyncTimer::every "10 secs" "00:00:00" {myCmd "Timer-One - every 10 secs"}]
   set t2  [SyncTimer::every "15 secs" "00:00:00" {myCmd "Timer-Two - every 15 secs"}]
   set t1a [SyncTimer::every "15 secs" "00:00:02" {myCmd "every 15 secs (+2)"}]
      
    # ... let them run for some minutes ...
      
   SyncTimer::cancel $t2
   SyncTimer::cancel $t1a
   SyncTimer::cancel $t1

NOTES

Event Loop: The SyncTimer command assumes that the application is event driven: the scheduled commands will not be executed unless the application enters the event loop. In applications that are not normally event-driven, such as tclsh, the event loop can be entered with the vwait and update commands. ( see also [after] command )
Min Interval: 1 second
Max Interval: 2**31 msec ( about 24 days and 20 hours)
No Delay Drift: Unexpected delays (due to the underlying event loop) are NOT summed up. If for any reason, a scheduled timer is started with some delay dT, the next time timer is triggered, it wont't sum up this delay.
Precision: Using SyncTimer, timers are synchronized with system clock with a precision of 1 millisecond. (Apart of delay due to the CPU scheduling).

HISTORY

1.0
- Initial revision
1.1
- Effort to synchronize timers with clock at milliseconds precision ( in 1.0 the precision was 1 sec. )
1.2
- Use of [clock milliseconds] command (new in Tcl 8.5) for a simpler and better synchronization.
- Note that this version does not work with Tcl 8.4.X