after(3tcl)

💖 after — bestie's guide to "do this thing later" 💖

okay so this is after, a Tcl Built-In Command, and it's literally the "wait a sec bestie" of the Tcl world. it delays stuff, or runs stuff in the background later. main character energy fr fr. 🌸

---

✨ SYNOPSIS ✨

after ms
after ms ?script script script ...?
after cancel id
after cancel script script script ...
after idle ?script script script ...?
after info ?id?

---

🦋 DESCRIPTION 🦋

so this command does one of two things: it delays execution of the program, or it executes a command in the background sometime in the future. it's giving "not right now but soon." it has several forms and which one you get depends on the first argument, so let's go one by one 💅

• after ms — ms has to be an integer giving a time in milliseconds. a negative number gets treated as 0. the command sleeps for ms milliseconds and then returns. and here's the tea: while the command is sleeping, the application does not respond to events. like at all. it's fully checked out. 😭
• after ms ?script script script ...? — this form returns immediately, but it sets up a Tcl command to run ms milliseconds later as an event handler. the command gets executed exactly once, at the given time. the delayed command is made by concatenating all the script arguments in the same fashion as the concat command. it runs at global level (so outside the context of any Tcl procedure, no sneaky local vars). if an error happens while the delayed command runs, then the background error gets reported by the command registered with interp bgerror. the after command returns an identifier you can use to cancel it with after cancel. and a ms value of 0 (or negative) queues the event immediately with priority over other event types — unless it was installed with an event proc, in which case it'll wait for the next round of events. periodt.
• after cancel id — cancels the execution of a delayed command that was scheduled earlier. id says which command to cancel, and it must have been the return value from a previous after command. if the command given by id has already been executed, then after cancel just... has no effect. no drama, nothing happens. 💀
• after cancel script script ... — yep, this one also cancels a delayed command. the script arguments get concatenated together with space separators (just as in the concat command). if there's a pending command that matches the string, it's canceled and will never be executed. if no such command is currently pending, then after cancel has no effect. that's it, that's the whole vibe.
• after idle script ?script script ...? — concatenates the script arguments together with space separators (just as in the concat command), and arranges for the resulting script to be evaluated later as an idle callback. the script runs exactly once, the next time the event loop is entered and there are no events to process. it returns an identifier you can use to cancel it with after cancel. if an error occurs while executing the script, then the background error gets reported by the command registered with interp bgerror. 🧚
• after info ?id? — this one is the gossip girl of the group: it returns information about existing event handlers. if no id argument is supplied, it returns a list of the identifiers for all existing event handlers created by the after command for this interpreter. if id is supplied, it specifies an existing handler — id must have been the return value from some previous call to after, and it must not have triggered yet or been canceled. in that case the command returns a list with two elements: the first element is the script associated with id, and the second element is either idle or timer to indicate what kind of event handler it is. iconic. 👑

---

heads up bestie: the after ms and after idle forms assume that the application is event driven. the delayed commands will not be executed unless the application enters the event loop. in applications that aren't normally event-driven, like tclsh, you can enter the event loop with the vwait and update commands. iykyk. 🫶

---

🌈 EXAMPLES 🌈

this one defines a command to make Tcl do nothing at all for N seconds:

proc sleep {N} {
    after [expr {int($N * 1000)}]
}

this arranges for the command wake_up to be run in eight hours (providing the event loop is active at that time):

after [expr {1000 * 60 * 60 * 8}] wake_up

and the following command can be used to do long-running calculations (as represented here by ::my_calc::one_step, which is assumed to return a boolean indicating whether another step should be performed) in a step-by-step fashion — though the calculation itself needs to be arranged so it can work step-wise. this technique is extra careful to make sure the event loop isn't starved by the rescheduling of processing steps (it arranges for the next step to be done using an already-triggered timer event only when the event queue has been drained), and it's super useful when you want to make sure a Tk GUI stays responsive during a slow task. queen behaviour. 💅

proc doOneStep {} {
    if {[::my_calc::one_step]} {
        after idle [list after 0 doOneStep]
    }
}
doOneStep

---

👀 SEE ALSO 👀

concat(3tcl), interp(3tcl), update(3tcl), vwait(3tcl)

---

🔑 KEYWORDS 🔑

cancel, delay, idle callback, sleep, time

---

and that's the whole page bestie!! this one comes from the Tcl Built-In Commands manual, Tcl version 7.5, after(3tcl) 💖✨🎀🦋 go schedule something and slay 🫶