NAME

ep_timer - An [incr Tcl] class for periodic or one-shot timing.

SYNOPSIS

package require Humelib
ep_timer timer_id [-option_name option_value]*
timer_id  at timestamp [UTC  [action]]
timer_id  cancel
timer_id  next_time
timer_id  run [action]
timer_id  run_at timestamp [UTC  [action]]

INHERITANCE

None

OPTIONS (PUBLIC VARIABLES)

Command-Line Switch: -MB_EPC Default value: {}

The default future action of the ep_timer is to send a timer event message to the Event Processing Component, EPC. The MB_EPC option influences how a timer event is posted to the EPC.
  1. If the MB_EPC value is non-blank, it is used as the DMH mailbox name of the EPC, and the event message is sent using the mbx command.
  2. Else if the MB_EPC value is blank, if the command ep_post_event is available, it is used to post the event.
  3. Otherwise a background error is issued.

Command-Line Switch: -MID Default value: {}

If the MID value is non-blank, when posting a timer event, the ep_timer will add the name-value pair of MID and $MID to the timer event data.

Command-Line Switch: -offset Default value: 00:00

The offset value is formatted as hh:mm or hh:mm:ss. Periodic actions can be configured using the period and offset public variables combined with calling the run method.  With this alternative,  the offset time is added to the beginning of the current day, and then an integral number of periods is added until a future event time is computed.  Subsequent future event times are computed by adding the period interval to each future event time.

Command-Line Switch: -period Default value: 00:01

The period value is formatted as hh:mm, hh:mm:ss, hhhh:mm, or hhhh:mm:ss.  The period value should be less than or equal to a year's duration. The period value specifies the time interval between periodic actions and is only used with the run and run_at methods.

DESCRIPTION

The ep_timer command creates a new Tcl command whose name is timer_id. The command is then used to initiate actions in the future - either one-shot or periodic.  The ep_timer class was developed as part of the Event Processing Component (EPC), but it can be used generally.

There are two ways to initiate periodic actions.  The first way is to set the period using the public variable, period, and to call the run_at method to begin periodic actions from a specified time.  Alternatively, periodic actions can be configured using the period and offset public variables combined with calling the run method.  With this alternative,  the offset time is added to the beginning of the current day, and then an integral number of periods is added until a future event time is computed.  Subsequent future event times are computed by adding the period interval to each future event time.

The class can be used for general timing purposes by supplying Tcl code for the action argument to the run, run_at, or at methods.  The default action is to send a timer event message to the EPC.  The format of the timer event message sent to the EPC is:

"event_id TIMER.timer_id timer_id timer_id"
or 
"event_id TIMER.timer_id timer_id timer_id MID MID"
if the MID value is non-blank.

The cancel method is used to stop the periodic actions, or to stop a one-shot action.

One-shot actions are scheduled for future execution by calling the at method. 

A timer is designed to be used for only a single future action, either one-shot or periodic.  Use multiple timer instances to have multiple future actions.  Timers use the Tcl after command for implementation which is supported by the Tcl/Tk event loop, and does not incur busy polling.  A timer can be used for a new action after it has become idle from being cancelled or from executing a one-shot action. 

The temporal accuracy of the timer event is typically well within a tenth of a second of the specified time, but may vary depending on the busyness of processing.   Accuracy is diminished by scheduling multiple tasks to occur at the same instant.  For best accuracy in measuring rates, use the timer events as a data acquisition trigger, and divide the occurrence count over the actual time period instead of the scheduled period.

CLASS METHODS

timer_id at timestamp [UTC  [action]]
One-shot actions are scheduled for future execution by calling the at method.  The timestamp argument to the at method specifies the time when the action should be executed in the localtime 9 or 15 formats.  When the  UTC argument is set to 1, the timestamp argument is interpreted as a Universal Coordinated Time value.

timer_id cancel
The cancel method is used to stop the periodic actions, or to stop a one-shot action.

timer_id next_time
When the timer is idle, the next_time method returns an empty string value.  When the timer is in active use, the next_time method returns the timestamp when the next action is scheduled to occur in the localtime 16 format.  When the next_time method is called during execution of periodic action code, the value obtained is for the next future execution and not the current one.

timer_id run [action]
The run method is called to begin periodic actions starting from the closest future time computed from the offset and period values.

timer_id run_at timestamp [UTC  [action]]
The run_at method is called to begin periodic actions from a specified time.

EXAMPLE

package require Humelib
catch {delete object timer_$mid}
# send an event to the EPC every minute
ep_timer timer_$mid -period 00:01 -MID $mid 
timer_$mid run

AUTHOR

Hume Integration Software, www.hume.com

KEYWORDS

after, EPC, one-shot, periodic, schedule, time