multiplexer(n)

✨ multiplexer(n) — one-to-many communication with sockets ✨

ok so bestie, welcome to the multiplexer page 💖 the title up there is doing the whole "one-to-many communication with sockets" thing and honestly? iconic. let's get into it.

---

🌸 SYNOPSIS 🌸

package require Tcl 8.5 9

package require logger

package require multiplexer ?0.3?

::multiplexer::create

${multiplexer_instance}::Init port

${multiplexer_instance}::Config key value

${multiplexer_instance}::AddFilter cmdprefix

cmdprefix data chan clientaddress clientport

${multiplexer_instance}::AddAccessFilter cmdprefix

cmdprefix chan clientaddress clientport

${multiplexer_instance}::AddExitFilter cmdprefix

cmdprefix chan clientaddress clientport

---

💅 DESCRIPTION 💅

the multiplexer package hands you a whole generic system for one-to-many communication using sockets. think: a chat system where one person sends a message and it gets broadcast to literally everybody else who's connected. that vibe. 🦋

and yes, you can have multiple multiplexers running at the same time. no cap. several of them, all coexisting, living their best lives.

::multiplexer::create

this command makes a brand new multiplexer 'instance'. like so:

set mp [::multiplexer::create]

and then you can mess with that instance like:

${mp}::Init 35100

${multiplexer_instance}::Init port

this kicks off the multiplexer and gets it listening on the specified port. she's up, she's ready, she's listening 👑

${multiplexer_instance}::Config key value

use Config to configure the multiplexer instance. the config options available rn are:

• sendtoorigin — a boolean flag, bestie. if it's true, the sender gets a copy of the message they sent back. defaults to false.
• debuglevel — sets the debug level for the multiplexer instance, matching the levels the logger package defines: debug, info, notice, warn, error, critical.

${multiplexer_instance}::AddFilter cmdprefix

ok this one adds a filter for the data that passes through the multiplexer instance. the cmdprefix you register gets called when data arrives at the instance. if there's more than one filter command registered on that instance, they get called in the order you registered them, and each filter receives the result of the previous filter as its argument. the first filter gets the incoming data as its argument. and whatever the last filter returns? that's the data that gets broadcast to every client of the multiplexer instance. periodt. 💫

the command prefix is called as:

cmdprefix data chan clientaddress clientport

• it takes the incoming data, modifies it, and returns that as its result.
• the last three arguments are all about the client that sent the data in to be filtered: the chan (the channel connecting us to the client), its clientaddress (the ip-address), and its clientport (the ip-port).

${multiplexer_instance}::AddAccessFilter cmdprefix

this adds an access filter 🌈 the cmdprefix you register gets called when a new client socket tries to connect to the multiplexer instance. if more than one access filter command is registered on the instance, they get called in the order you registered them.

and here's the gatekeeping part, iykyk: if any of the called commands returns -1, access to the multiplexer instance is denied and the client channel is closed immediately. literally slammed the door. any other result at all grants the client access to the multiplexer instance. 🫶

the command prefix is called as:

cmdprefix chan clientaddress clientport

• the arguments are all about the client trying to connect to the instance: the chan (channel connecting us to the client), its clientaddress (ip-address), and its clientport (ip-port).

${multiplexer_instance}::AddExitFilter cmdprefix

adds a filter that runs when a client socket generates an EOF condition 😭 the cmdprefix you register gets called when a client socket of the multiplexer signals EOF. if more than one exit filter command is registered on the instance, they get called in the order you registered them.

heads up bestie: errors thrown by an exit filter are ignored, but they do get logged. and any result an exit filter returns is ignored too. she's just there to vibe and do side quests.

the command prefix is called as:

cmdprefix chan clientaddress clientport

• the arguments are all about the client that signaled the EOF: the chan (channel connecting us to the client), its clientaddress (ip-address), and its clientport (ip-port).

---

💀 BUGS, IDEAS, FEEDBACK 💀

ngl, this document — and the package it describes — will undoubtedly contain bugs and other problems. it's giving "work in progress" and we respect it. please report those in the category multiplexer of the Tcllib Trackers at http://core.tcl.tk/tcllib/reportlist. and please also drop any ideas for enhancements you have for either the package and/or the documentation. we want them fr fr 🍓

when you're proposing code changes, please provide unified diffs, i.e. the output of diff -u.

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 its creation, and then using the left-most button in the secondary navigation bar. boom, done.

---

⭐ KEYWORDS ⭐

chat, multiplexer

---

🎀 CATEGORY 🎀

Programming tools

---

and that's the whole page, bestie 💜 this one's from tcllib, version 0.3, and it goes by multiplexer(n). go forth and multiplex, you absolute main character 👑