Tcl_DoWhenIdle(3tcl)

💖 Tcl_DoWhenIdle — invoke a procedure when there are no pending events 💖

okay bestie, welcome to the Tcl Library Procedures page for Tcl_DoWhenIdle, aka the manual page Tcl_DoWhenIdle(3tcl) ✨ it's giving "do the thing later, when everything's chill" and honestly? iconic.

---

✨ NAME ✨

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

---

🌸 SYNOPSIS 🌸

#include <tcl.h>

Tcl_DoWhenIdle(proc, clientData)

Tcl_CancelIdleCall(proc, clientData)

---

🎀 ARGUMENTS 🎀

• Tcl_IdleProc *proc (in) — the procedure you wanna invoke, bestie.
• void *clientData (in) — some arbitrary one-word value that gets passed along to proc. no cap, just one word.

---

💅 DESCRIPTION 💅

Tcl_DoWhenIdle sets it up so that proc gets invoked when the application becomes idle. and when is the app "idle", you ask? when Tcl_DoOneEvent has been called, could not find any events to handle, and is literally about to go to sleep waiting for an event to occur. that exact moment. and at that point, all the pending Tcl_DoWhenIdle handlers get invoked, one after another. periodt.

for each call to Tcl_DoWhenIdle there will be exactly one call to proc — not zero, not two, one — and after proc is invoked the handler is automatically removed. self-cleaning, main character energy honestly. 🙈

heads up though: Tcl_DoWhenIdle is only usable in programs that use Tcl_DoOneEvent to dispatch events. that's the whole vibe check, and if you fail it, this isn't for you.

proc should have arguments and a 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 you gave to Tcl_DoWhenIdle. typically, clientData points to a data structure holding application-specific info about what proc should actually do. like, the vibes are yours to define. 🫶

---

Tcl_CancelIdleCall is your undo button, bestie. use it to cancel one or more previous calls to Tcl_DoWhenIdle: if there's a Tcl_DoWhenIdle handler registered for proc and clientData, then it gets removed without invoking it. poof. gone. 💀

and if there's more than one handler on the idle list referring to proc and clientData, all of the handlers are removed. all of them. not just one. and if no existing handlers match proc and clientData? then literally nothing happens. no error, no drama, just silence. 🌸

---

so why would you even want this? Tcl_DoWhenIdle is most useful in situations where (a) a piece of work will have to be done but (b) it's possible that something will happen in the near future that will change what has to be done, or require something different to be done. classic. the way that it defers the actual work until all pending events have been processed is chef's kiss. at that point the exact work to be done will presumably be known, and it can be done exactly once. no wasted effort, no repeats, 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. imagine the flickering. we do not stan. 😭

---

💀 BUGS 💀

okay so, at present it is not safe for an idle callback to reschedule itself continuously. read that again. not safe. this will interact badly with certain features of Tk that attempt to wait for all idle callbacks to complete. 🙈

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. that's the move. iykyk. ⭐

---

🦋 SEE ALSO 🦋

• after(3tcl)
• Tcl_CreateFileHandler(3tcl)
• Tcl_CreateTimerHandler(3tcl)

---

👑 KEYWORDS 👑

callback, defer, idle callback

---

and that's the whole page, bestie!! this one's from the Tcl 7.5 era, and it's the Tcl_DoWhenIdle(3tcl) manual page in the Tcl Library Procedures. go forth and defer your work responsibly 💖✨🎀🦋🌸💅🫶