Tcl_Creat...elHandler(3tcl)

💖 Tcl_Creat...elHandler — bestie edition ✨

okay so real talk, this is the Tcl Library Procedures page for two little functions that let your channel go "hey girl, something's happening!!" and call you back. They are Tcl_CreateChannelHandler and Tcl_DeleteChannelHandler, and their whole job is calling a procedure when a channel becomes readable or writable. no cap.

---

🌸 NAME 🌸

Tcl_CreateChannelHandler, Tcl_DeleteChannelHandler — call a procedure when a channel becomes readable or writable 💅

---

🎀 SYNOPSIS 🎀

#include <tcl.h>

Tcl_CreateChannelHandler(channel, mask, proc, clientData)

Tcl_DeleteChannelHandler(channel, proc, clientData)

---

🦋 ARGUMENTS 🦋

• Tcl_Channel channel (in) — a Tcl channel, like the kind Tcl_CreateChannel hands you back. your main character channel fr.
• int mask (in) — the conditions under which proc should get called: an OR-ed combo of TCL_READABLE, TCL_WRITABLE and TCL_EXCEPTION. pass a zero value if you wanna temporarily disable an existing handler (girl's on a break, not deleted, just vibing offline).
• Tcl_ChannelProc *proc (in) — the procedure to invoke whenever the channel indicated by channel meets the conditions specified by mask. your callback. your ride-or-die.
• void *clientData (in) — an arbitrary one-word value to pass to proc. literally whatever you want, it's just getting handed back.

---

✨ DESCRIPTION ✨

Tcl_CreateChannelHandler arranges for proc to be called in the future whenever input or output becomes possible on the channel identified by channel, or whenever an exceptional condition exists for channel. the conditions of interest — the ones that make proc actually fire — are specified by the mask argument. if you want the precise definition of what it even means for a channel to be readable or writable, go read the manual entry for fileevent, she explains it way better than I can. 💀

proc must conform to this prototype, exactly:

typedef void Tcl_ChannelProc(
        void *clientData,
        int mask);

the clientData argument is the same as the value you passed to Tcl_CreateChannelHandler when the handler was created. typically, clientData points to a data structure containing application-specific information about the channel. so like, your lil info bundle. 🎁

mask is an integer mask indicating which of the requested conditions actually exists for the channel; it will contain a subset of the bits from the mask argument to Tcl_CreateChannelHandler when the handler was created. not the whole thing — just the bits that are actually popping off right now.

each channel handler is identified by a unique combination of channel, proc and clientData. there may be many handlers for a given channel, as long as they do not have the same channel, proc, and clientData. no duplicates allowed, that's the rule. 👑

if Tcl_CreateChannelHandler is invoked when there is already a handler for channel, proc, and clientData, then no new handler is created; instead, the mask is changed for the existing handler. so it's not adding a second one bestie, it's just updating the settings on the one you already have. periodt.

Tcl_DeleteChannelHandler deletes a channel handler identified by channel, proc and clientData; if no such handler exists, the call has no effect. nothing happens. no drama, no error, just a shrug. 🫶

channel handlers are invoked via the Tcl event mechanism, so they are only useful in applications that are event-driven. if your app isn't event-driven this is giving absolutely nothing, ngl.

⚠️ also note: the conditions specified in the mask argument to proc may no longer exist when proc is invoked. for example, if there are two handlers for TCL_READABLE on the same channel, the first handler could consume <em>all</em> of the available input so that the channel is no longer readable when the second handler is invoked. 😭 she ate and left no crumbs. for this reason it may be useful to use nonblocking I/O on channels for which there are event handlers.

---

💜 SEE ALSO 💜

Notifier(3tcl), Tcl_CreateChannel(3tcl), Tcl_OpenFileChannel(3tcl), vwait(3tcl)

---

⭐ KEYWORDS ⭐

blocking, callback, channel, events, handler, nonblocking

---

and that's the whole page bestie!! this one's from the Tcl library docs, version 7.5 — so yeah, she's been iconic since forever. go write some event-driven slay. 💖✨🎀