tclcron(n) 1.0 "Pure Tcl cron-like library using event loop"

NAME

tclcron - Pure Tcl cron-like library using event loop

    TABLE OF CONTENTS
    SYNOPSIS
    DESCRIPTION
    COMMAND
    SCHEDULING MODULES
    WRITING CUSTOM MODULES
    KEYWORDS
    COPYRIGHT

SYNOPSIS

package require Tcl 8.4
package require tclcron ?1.0?

::tclcron::schedule command type args

::tclcron::unschedule identifier

::tclcron::info ?commandPattern?

::tclcron::schedules identifier ?limit? ?seconds?

::tclcron::<packageName>::initialize identifier parameters

::tclcron::<packageName>::schedulenext parametersVariable clock

DESCRIPTION

This module allows writing long running applications that need to periodically do jobs, similar to what cron offers.

It consists of modular scheduling commands, which allow setting up

COMMAND

::tclcron::schedule command type args

Schedule a command execution at specified interval or at specified times.

Type indicates a type of scheduling module that should be used. See information in SCHEDULING MODULES for a list of available types.

If a procedure causes a background error, it is thrown back using bgerror, but it is continued to be called.

tclcron::schedule {
    puts "Another minute has passed"
} every 60 seconds

::tclcron::unschedule identifier

Unschedule next executions of a command. The identifier is a result of a previous tclcron::schedule command.

::tclcron::info ?commandPattern?

Retrieve a list of all commands, or command matching specified pattern. This command returns a list of 4-element groups, where each element is described by identifier, Tcl command, type and typeArguments.

::tclcron::schedules identifier ?limit? ?seconds?

Retrieve a list of times at which an event should be run. This command returns a list seconds that can then be used for clock command.

This command is mainly intended for testing and debugging. It helps finding when a job will be executed.

SCHEDULING MODULES

Scheduling module is a module that establishes next time a procedure is going to be called.

Blah

every

Schedules procedures at either specified interval or at specified dates. All additional parameters are passed to clock scan command for further parsing.

tclcron::schedule {puts "Tick"} every 1 second

once

Schedules a procedure once, at a specified time. All additional parameters are passed to clock scan command for further parsing.

lonce

Schedules a procedure once or several times. Each additional parameter is passed separately to clock scan command for further parsing.

tclcron::schedule {
    puts "It's friday or saturday, but it's 22:00"
} lonce {friday 22:00} {saturday 22:00}

combine

This module allows combining several scheduling modules into one scheduled job. Each additional parameter is assumed to be a list, where the first element is the module type to use and all additional elements are additional parameters that need to be passed to that module.

The example below

tclcron::schedule {
    puts "It's either 22:00 or 23:00"
} combine {every 22:00} {every 23:00}

is very similar to

tclcron::schedule {
    puts "It's either 22:00 or 23:00"
} combine {every 22:00}

tclcron::schedule {
    puts "It's either 22:00 or 23:00"
} combine {every 23:00}

except that combine module does not allow calling the same procedure twice at one time and can be unscheduled by calling a single tclcron::unschedule.

WRITING CUSTOM MODULES

Writing a module is a very simple task. It should simply provide a package called tclcron::tclcron_<packageName>. The package should create a namespace called tclcron::<packageName> and the package should provide the following procedures:

::tclcron::<packageName>::initialize identifier parameters

A function that parser and/or initializes the module. It should return parameters in the way they should be stored and passed on to calls to schedulenext procedure. If the parameters do not need to be changed or no action needs to be taken, all that is required is to return parameters back.

::tclcron::<packageName>::schedulenext parametersVariable clock

This function is called each time a job needs to determine the next time it needs to be scheduled. Parameters are passed as a variable name to allow modules to store data and/or change the parameters as needed.

The following is an example of how to implement a scheduling module, at the same time it is a working code of the module every.

package provide tclcron::tclcron_every 1.0

namespace eval tclcron {}
namespace eval tclcron::every {}

proc tclcron::every::initialize {idx params} {
    return $params
}

proc tclcron::every::schedulenext {argsvar clock} {
    upvar $argsvar ar
    return [clock scan $ar -base $clock]
}

KEYWORDS

cron, tcl