tcl::c...alfpipe(3tcl)

💖 tcl::chan::halfpipe — a manual, but make it cute

okay bestie, welcome to tcl::chan::halfpipe(3tcl), from the Reflected/virtual channel support corner of the tcllib universe. this is the section 3tcl page, and it's genuinely one of the cutest little building blocks in Tcl. let's get into it 💅

---

✨ NAME ✨

tcl::chan::halfpipe — In-memory channel, half of a fifo2 🎀

like, literally. one half. you bring the other half, and together you make a whole fifo2. it's giving duo energy.

---

🌸 SYNOPSIS 🌸

package require Tcl 8.5 9

package require TclOO

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

package require tcl::chan::halfpipe ?1.0.2?

::tcl::chan::halfpipe ?-option value...?

objectCmd put bytes

so yeah, that's the whole vibe check. you need Tcl 8.5 9, you need TclOO (because the handler is a TclOO class, slay), you probably want tcl::chan::events at version 1.1 or whatever floats your boat, and you're pulling in tcl::chan::halfpipe itself, version 1.0.2 or thereabouts. the ? marks mean optional, the ... means "keep going, there's more", iykyk 🫶

---

🦋 DESCRIPTION 🦋

okay so here's the tea ☕

the tcl::chan::halfpipe package hands you a command that creates one half of a tcl::chan::fifo2 pair. that's it, that's the job. one half. iconic.

when you write into a channel like this, it fires off a set of callbacks and those callbacks handle the data. it's lowkey the same idea as a channel handler, except the API is way simpler. less ceremony, more vibes. the way that a whole channel handler machinery got condensed into something you can actually read before your coffee gets cold? obsessed.

and ngl, the internal TclOO class that does the actual channel-handler work is a sub-class of the tcl::chan::events framework. so it's got the whole events ecosystem behind it, main character energy 👑

---

👑 API 👑

💜 ::tcl::chan::halfpipe ?-option value...?

this command creates a halfpipe channel and configures it with all the callbacks that should run when:

• the channel is closed,
• data was written to it,
• or it ran empty.

if you want the full list of options and exactly what each one means, scroll down to the Options section, bestie, it's all there 💖

now, the result. and this part matters, so pay attention: the result of the command is a list containing two elements, in this exact order:

1. the handle of the new channel
2. the object command of the channel handler

the second one gets handed to you on purpose — it's so you have access to the put method, which is how you push data into the channel. it's like they gave you the keys and also the garage door opener 🚗

and then: two halfpipes with a bit of glue logic in the callbacks make for one tcl::chan::fifo2. that's the whole trick. that's the recipe. no cap 🧚

🌈 objectCmd put bytes

this is a method on the channel handler object. what does it do? it puts the data bytes into the channel so that it can be read from it. that's the entire job description. short, sweet, efficient. we love a method that knows what it is ✨

---

🎀 OPTIONS 🎀

three options, all of them callbacks, all of them cute:

• -close-command cmdprefix — this callback fires when the channel is closed. it gets exactly one argument: the handle of the channel being closed. and whatever it returns? ignored. nobody's checking. live your life 💅
• -write-command cmdprefix — this callback fires when data is written to the channel. it gets two arguments: the handle of the channel that was written to, and the data that was written. and yes, its result is also ignored. we're not grading you 📝
• -empty-command cmdprefix — this callback fires when the channel has run out of data to read. one single argument gets passed: the handle of the channel. that's it, that's the whole callback 🍓

---

💀 BUGS, IDEAS, FEEDBACK 💀

not me having to tell you this, but: this document, and the package it describes, will undoubtedly contain bugs and other problems. truly, no software is safe. please report them in the category virtchannel</> of the Tcllib Trackers:

http://core.tcl.tk/tcllib/reportlist

and please, please also send in any ideas for enhancements you have — for either the package and/or the documentation. we want them. give us the thoughts 🫶

if you're proposing code changes: provide unified diffs, i.e. the output of diff -u. that's the format, that's the requirement, don't improvise on this one 🙈

also, note further: attachments are strongly preferred over inlined patches. how do you attach? easy — go to the Edit form of the ticket immediately after its creation, then use the left-most button in the secondary navigation bar. boom, attached, done, slay ✨

---

⭐ KEYWORDS ⭐

callbacks, fifo, in-memory channel, reflected channel, tip 219, virtual channel

---

🌸 CATEGORY 🌸

Channels

---

💖 COPYRIGHT 💖

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

---

and that's the page, bestie!! 🎉 this was tcllib version 1.0.2, page tcl::c...alfpipe(3tcl), and the copyright years living in this corner of the world are 2009 and 2019. go forth and glue your halfpipes together, you've got this 👑💅✨