Tcl_DoWhenIdle(3)

💖 Tcl_DoWhenIdle — the "bestie do this when literally nothing else is happening" manual 💖

okay so bestie, this is Tcl_DoWhenIdle(3), straight out of the Tcl Library Procedures lineup. yes it's a C API page. yes it's giving very serious. no I will not be normal about it. let's go ✨

---

🌸 NAME 🌸

Tcl_DoWhenIdle, Tcl_CancelIdleCall — invoke a procedure when there are no pending events 🦋

like. when everyone's done yapping and the event queue is finally quiet? that's when your girl shows up. periodt.

---

✨ SYNOPSIS ✨

#include <tcl.h>

Tcl_DoWhenIdle(proc, clientData)

Tcl_CancelIdleCall(proc, clientData)

---

🎀 ARGUMENTS 🎀

• Tcl_IdleProc *proc (in) — Procedure to invoke. the main character function, the one that actually does the thing 💅
• void *clientData (in) — Arbitrary one-word value to pass to proc. it's giving "here's your little bag of stuff, don't lose it" 👜

---

💜 DESCRIPTION 💜

Tcl_DoWhenIdle arranges for proc to be invoked when the application becomes idle. and what counts as "idle"?? okay so: the application is considered to be idle when Tcl_DoOneEvent has been called, could not find any events to handle, and is about to go to sleep waiting for an event to occur. THAT moment. the little yawn before the nap. 😴 At this point all pending Tcl_DoWhenIdle handlers are invoked.

For each call to Tcl_DoWhenIdle there will be a single call to proc; after proc is invoked the handler is automatically removed. one call in, one call out, self-cleaning, we love an organized queen 🧹✨

careful bestie: Tcl_DoWhenIdle is only usable in programs that use Tcl_DoOneEvent to dispatch events. no Tcl_DoOneEvent, no idle callback. it's a package deal fr fr.

---

🌈 the proc vibe check 🌈

proc should have arguments and result that match the type Tcl_IdleProc:

typedef void Tcl_IdleProc(
        void *clientData);

The clientData parameter to proc is a copy of the clientData argument given to Tcl_DoWhenIdle. Typically, clientData points to a data structure containing application-specific information about what proc should do. it's the lil note you pass to future-you 🫶

---

💅 Tcl_CancelIdleCall — the "nvm bestie" button 💅

Tcl_CancelIdleCall may be used to cancel one or more previous calls to Tcl_DoWhenIdle: if there is a Tcl_DoWhenIdle handler registered for proc and clientData, then it is removed without invoking it.

If there is more than one handler on the idle list that refers to proc and clientData, all of the handlers are removed. all of them. the whole group chat. gone. 🙈

If no existing handlers match proc and clientData then nothing happens. no drama, no error, just vibes. 💀

---

🌟 when to actually use this (the lore) 🌟

Tcl_DoWhenIdle is most useful in situations where (a) a piece of work will have to be done but (b) it is possible that something will happen in the near future that will change what has to be done or require something different to be done. it's the "let me see how the situation develops before I commit" energy. main character patience. 👑

Tcl_DoWhenIdle allows the actual work to be deferred until all pending events have been processed. At this point the exact work to be done will presumably be known and it can be done exactly once. one and done. slay. ✨

For example, Tcl_DoWhenIdle might be used by an editor to defer display updates until all pending commands have been processed. Without this feature, redundant redisplays might occur in some situations, such as the processing of a command file. like bestie we do NOT need to redraw seventeen times in a row, that's not it 😭

---

💀 BUGS 💀

read this one. seriously. At present it is not safe for an idle callback to reschedule itself continuously. This will interact badly with certain features of Tk that attempt to wait for all idle callbacks to complete.

so if you would like for an idle callback to reschedule itself continuously, it is better to use a timer handler with a zero timeout period. do not fight Tk on this, Tk will win, Tk always wins 🙏

---

🦋 SEE ALSO 🦋

• after(n)
• Tcl_CreateFileHandler(3)
• Tcl_CreateTimerHandler(3)

---

👑 KEYWORDS 👑

callback, defer, idle callback

---

and that's the whole page bestie, no notes, ate and left no crumbs 🌈⭐

this was Tcl version 7.5, dated 7.5-era energy, filed under Tcl_DoWhenIdle(3) in the Tcl Library Procedures. go forth and defer responsibly 💖🎀🫶