tcl::c...:events(3tcl)

✨ NAME ✨

tcl::chan::events — event support for reflected/virtual channels, bestie 💖

So real talk: this page lives in the Reflected/virtual channel support corner of the manual, and it's giving very much "the plumbing that makes event-driven IO work on virtual channels". Let's get into it 🫶

---

🌸 SYNOPSIS 🌸

package require Tcl 8.5 9

package require TclOO

package require tcl::chan::core ?1.1?

package require tcl::chan::events ?1.1?

::tcl::chan::events objectName

objectName finalize thechannel

objectName watch thechannel eventmask

objectName allow eventname...

objectName disallow eventname...

Like, that's the whole vibe check right there. Note the ?1.1? bits — those are version specs, optional-looking but very much part of the requirements, okurrr 👑

---

🦋 DESCRIPTION 🦋

The tcl::chan::events package hands you a TclOO class that implements the common behaviour basically every reflected or virtual channel needs when it's doing event-driven IO. It is a sub-class of tcl::chan::core, and it inherits all of that class's behaviour. No cap, all of it 💅

This class is designed to be used one of two ways: as the superclass of a concrete channel class, or mixed into such a class. Either way works, pick your fighter ✨

---

👑 CLASS API 👑

• ::tcl::chan::events objectName — creates a brand-new channel event core object, with an associated global Tcl command whose name is objectName. That command is your key to invoking the various operations on the object, all described down in the Instance API section. Main character energy fr 🌟

---

💖 INSTANCE API 💖

The API of channel event core instances is a small menu — only four methods. Two of them line up with channel handler commands (for reference, peep TIP 219 at http:/tip.tcl.tk/219), and the other two are there for sub-classes to control event generation. The first kind expects to be called from whichever object instance the channel event core got made a part of. It's giving teamwork 🫶

• objectName finalize thechannel — this method implements the standard behaviour for the finalize method of channel handlers. It overrides what it inherited from tcl::chan::core, and on top of that it disables any and all event generation before destroying itself. Iconic exit, honestly 😭✨
• objectName watch thechannel eventmask — this method implements the standard behaviour for the watch method of channel handlers. The IO system calls it whenever the interest in events changes, and it updates the instance state so the generation of the events of (non-)interest gets activated and/or suppressed. Basically it's the "not me adjusting the settings" moment 💀
• objectName allow eventname...
• objectName disallow eventname...

These two methods are exported to sub-classes, so that their instances can notify their event core about which events the channel they implement can (allow) or cannot (disallow) generate. Combine that with the info about events requested by Tcl's IO system coming in through the watch method, and the event core can figure out which events it should (not) generate, and act accordingly. Teamwork makes the dream work, periodt 🌈

---

🙈 BUGS, IDEAS, FEEDBACK 🙈

Okay so, real talk: this document, and the package it describes, will undoubtedly contain bugs and other problems. Not a vibe, but it's the truth 😭 Please report them in the category virtchannel of the Tcllib Trackers over at http://core.tcl.tk/tcllib/reportlist. And please also drop any ideas for enhancements you may have for either the package and/or the documentation — we want them all 🎀

When you're proposing code changes, please provide unified diffs, i.e. the output of diff -u. Fr fr, that's the format.

Also note: attachments are strongly preferred over inlined patches. You can make an attachment by going to the Edit form of the ticket immediately after creating it, and then using the left-most button in the secondary navigation bar. iykyk 💅

---

⭐ KEYWORDS ⭐

• event management
• reflected channel
• tip 219
• virtual channel

---

🍓 CATEGORY 🍓

Channels

---

💜 COPYRIGHT 💜

Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net>

---

And that's the whole page, bestie! This one's from tcllib, version 1.1, and the page itself is tcl::c...:events(3tcl). Slay, go forth and build your virtual channels 💖✨🎀