cron(3tcl)

🌸 NAME 🌸

cron — the tool for automating the period callback of commands 💅

---

✨ SYNOPSIS ✨

okay bestie, here's the whole vibe check upfront:

package require Tcl 8.6 9

package require cron ?2.2?

::cron::at ?processname? timecode command

::cron::cancel processname

::cron::every processname frequency command

::cron::in ?processname? timecode command

::cron::object_coroutine object coroutine ?info?

::cron::sleep milliseconds

::cron::task delete process

::cron::task exists process

::cron::task info process

::cron::task set process field value ?field...? ?value...?

::cron::wake ?who?

::cron::clock_step milliseconds

::cron::clock_delay milliseconds

::cron::clock_sleep seconds ?offset?

::cron::clock_set newtime

---

🦋 DESCRIPTION 🦋

So the cron package is a Pure-tcl set of tools that lets your program schedule tasks to happen at regular intervals 🎀. Instead of making every single task go and issue its own call to the event loop (so much drama, so much chaos), the cron system copies what the cron utility does in Unix: one task periodically checks whether something needs doing, and then fires off all the commands for a given time step in one go. iconic behaviour honestly 👑

💫 Changes in version 2.0

ngl, cron started out only handling time scales bigger than 1 second, but the latest version's internals understand time granularity all the way down to the millisecond, which makes it way easier to integrate with other timed events ✨. Version 2.0 also knows how to properly integrate coroutines and objects. It also adds a facility for an external (or script driven) clock 🕰️.

heads up bestie: vwait style events won't work very well with an external clock. that's just the truth of it 😭

---

👑 COMMANDS 👑

• ::cron::at ?processname? timecode command — this one registers a command to be called at the time given by timecode. If timecode is an integer, it's assumed to be in unixtime 🕐. Every other kind of input gets run through clock scan and converted to unix time. You can modify this task later by calling this package's commands and referencing processname. If processname already exists, it gets replaced 💀. If you don't give a processname, one gets generated for you and handed back by the command.

::cron::at start_coffee {Tomorrow at 9:00am}  {remote::exec::coffeepot power on}
::cron::at shutdown_coffee {Tomorrow at 12:00pm}  {remote::exec::coffeepot power off}

• ::cron::cancel processname — unregisters the process processname and cancels any pending commands 🙅♀️. Quick note: processname can be a process created by either ::cron::at or ::cron::every.

::cron::cancel check_mail

• ::cron::every processname frequency command — registers a command to be called at an interval of frequency ⏰. frequency is given in seconds. You can modify this task later by calling this package's commands and referencing processname. If processname already exists, it gets replaced.

::cron::every check_mail 900  ::imap_client::check_mail
::cron::every backup_db  3600 {::backup_procedure ::mydb}

• ::cron::in ?processname? timecode command — registers a command to be called after a delay of the time specified by timecode ⏳. timecode is expressed as an seconds. You can modify this task later by calling this package's commands and referencing processname. If processname already exists, it gets replaced. If you don't give a processname, one is generated and returned by the command.
• ::cron::object_coroutine object coroutine ?info? — registers a coroutine, associated with object, to be called given the parameters of info 🧚. If now parameters are given, the coroutine is assumed to be an idle task which will self-terminate. info can be given in any form compadible with ::cron::task set.
• ::cron::sleep milliseconds — when you run this inside a coroutine, it registers the coroutine for a callback at the appointed time and immediately yields 😴.

If the ::cron::time variable is > 0, this command will advance the internal time, 100ms at a time.

In all other cases, this command generates a fictious variable, generates an after call, and vwaits the variable:

set eventid [incr ::cron::eventcount]
set var ::cron::event_#$eventid
set $var 0
::after $ms "set $var 1"
::vwait $var
::unset $var

Usage:

::cron::sleep 250

• ::cron::task delete process — deletes the process specified the process 🗑️
• ::cron::task exists process — returns true if process is registered with cron ✅
• ::cron::task info process — returns a dict describing process. Peep ::cron::task set for a description of the options 👀
• ::cron::task set process field value ?field...? ?value...? — if process doesn't exist, it gets created ✨. Options include:
  • command — if coroutine is black, a global command which implements this process. If coroutine is not black, the command to invoke to create or recreate the coroutine.
  • coroutine — the name of the coroutine (if any) which implements this process.
  • frequency — if -1, this process is terminated after the next event. If 0, this process should be called during every idle event. If positive, this process should generate events periodically. The frequency is an integer number of milliseconds between events.
  • object — the object associated with this process or coroutine.
  • scheduled — if non-zero, the absolute time from the epoch (in milliseconds) that this process will trigger an event. If zero, and the frequency is also zero, this process is called every idle loop.
  • running — a boolean flag. If true it indicates the process never returned or yielded during the event loop, and will not be called again until it does so.
• ::cron::wake ?who? — wake up cron 😤, and arrange for its event loop to be run during the next Idle cycle.

::cron::wake {I just did something important}

---

Several utility commands are provided that are used internally within cron and for testing cron, but may or may not be useful in the general cases 🤷♀️

• ::cron::clock_step milliseconds — return a clock time absolute to the epoch which falls on the next border between one second and the next for the value of milliseconds ⏱️
• ::cron::clock_delay milliseconds — return a clock time absolute to the epoch which falls on the next border between one second and the next milliseconds in the future.
• ::cron::clock_sleep seconds ?offset? — return a clock time absolute to the epoch which falls exactly seconds in the future. If offset is given it may be positive or negative, and will shift the final time to before or after the second would flip 🔄
• ::cron::clock_set newtime — sets the internal clock for cron. This command will advance the time in 100ms increment, triggering events, until the internal time catches up with newtime.

newtime is expressed in absolute milliseconds since the beginning of the epoch.

---

😭 BUGS, IDEAS, FEEDBACK 😭

This document, and the package it describes, will undoubtedly contain bugs and other problems 💀. Please report such in the category odie of the Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist]. Please also report any ideas for enhancements you may have for either package and/or documentation — we want the glow-up fr fr 🫶

When proposing code changes, please provide unified diffs, i.e the output of diff -u.

Note further that attachments are strongly preferred over inlined patches. Attachments can be made by going to the Edit form of the ticket immediately after its creation, and then using the left-most button in the secondary navigation bar.

---

🎀 KEYWORDS 🎀

cron, odie

---

💜 CATEGORY 💜

System

---

🌈 COPYRIGHT 🌈

Copyright (c) 2016-2018 Sean Woods <yoda@etoyoc.com>

---

and that's the whole page bestie ✨💖 this was cron(3tcl) out of tcllib, version 2.2 — slay, go schedule something, and remember: one task checking everything is main character energy 👑🦋