coroutine(3tcl)

🌸 coroutine — Coroutine utilities 💅

ok so bestie, this is the manual for coroutine(3tcl) from tcllib, and honestly? it's giving green threads but make it cute. sit down, grab a boba, we're doing this. ✨

---

✨ NAME ✨

coroutine — coroutine based event and IO handling. that's it, that's the name, she's simple and she knows it 🫶

---

🎀 SYNOPSIS 🎀

package require Tcl 8.6 9

package require coroutine 1.4

coroutine::util after delay

coroutine::util await varname...

coroutine::util create arg...

coroutine::util exit ?status?

coroutine::util gets chan ?varname?

coroutine::util gets_safety chan limit varname

coroutine::util global varname...

coroutine::util puts ?-nonewline? channel string

coroutine::util read -nonewline chan ?n?

coroutine::util socket ?options...? host port

coroutine::util update ?idletasks?

coroutine::util vwait varname

---

💖 DESCRIPTION 💖

the coroutine package hands you coroutine-aware versions of a whole bunch of event- and channel-related commands. like, the regular ones but they actually know what a coroutine is. iconic behaviour honestly.

and you can run it in multiple modes, pick your fighter:

1. call the commands through their ensemble, in code that was explicitly written to live inside coroutines. you know, the code that knows what it is. main character energy 💅
2. import the commands into a namespace — either directly or through namespace path. this lets you use them from code that is not coroutine-aware per se and is restricted to specific namespaces. sneaky but legal. 🧚

and there's an even more aggressive version of this whole "make your code forget coroutines exist" thing than point 2 up there — it's available through the package coroutine::auto, which intercepts the relevant builtin commands and swaps out their implementation depending on the context they're run in. i.e. whether they're inside or outside a coroutine. she just knows. 🔥

---

🌈 API 🌈

every single command listed below is synchronous with respect to the coroutine invoking it, i.e. that coroutine blocks until the result is available. but bestie, the overall eventloop is not blocked. the world keeps spinning, only you are waiting. no cap. ✨

---

• coroutine::util after delay — this command delays the coroutine invoking it by delay milliseconds. that's it. it's a nap. take the nap. 😴
• coroutine::util await varname... — this one is an extension form of the coroutine::util vwait command (scroll down, she's there 💕). it waits on a write to one of many named namespace variables. plural. the whole squad.
• coroutine::util create arg... — creates a new coroutine with an automatically assigned name and causes it to run the code specified by the arguments. surprise baby, no name needed. 🦋
• coroutine::util exit ?status? — exits the current coroutine, causing it to return status. if no status was specified, the default 0 is returned. bye bestie, exit with dignity 💀
• coroutine::util gets chan ?varname? — reads a line from the channel chan and returns it either as its result, or — if a varname was specified — writes it to the named variable and returns the number of characters read. two ways to get your tea ☕
• coroutine::util gets_safety chan limit varname — reads a line from the channel chan up to size limit and stores the result in varname. if the limit is reached before the first newline shows up, an error is thrown. it's the safety rails version, she's cautious and we love her for it 🎀 the command returns the number of characters read.
• coroutine::util global varname... — imports the named global variables of the coroutine into the current scope. technically speaking, these variables reside in level #1 of the Tcl stack. so no, these are not the regular globals in the global namespace — each coroutine can have its own set, completely independent of all the others. your own lil private stash 💜
• coroutine::util puts ?-nonewline? channel string — writes the string to the specified channel. and contrary to the builtin puts, this one waits until the channel is actually writable before writing to it. patient queen 👑
• coroutine::util read -nonewline chan ?n? — reads n characters from the channel chan and returns them as its result. if n isn't specified, the command reads the channel until EOF is reached. the whole thing. all of it. 🙈
• coroutine::util socket ?options...? host port — connects to the specified host and port and returns when that's done. contrary to the builtin command, it performs a non-blocking connect in the background. so yeah, it blocks the calling coroutine, but the overall application is not blocked. everybody else keeps vibing ⭐
• coroutine::util update ?idletasks? — causes the coroutine invoking it to run pending events or idle handlers before proceeding. like checking your notifs before you continue the convo 📱
• coroutine::util vwait varname — causes the coroutine calling it to wait for a write to the named namespace variable varname. one variable, one wait, lots of patience 🌸

---

💀 BUGS, IDEAS, FEEDBACK 💀

this document, and the package it describes, will undoubtedly contain bugs and other problems. we're being honest upfront, that's growth. 😭

please report such in the category coroutine of the Tcllib Trackers at http://core.tcl.tk/tcllib/reportlist. please also report any ideas for enhancements you may have for either the package and/or the documentation. we want the ideas, we want all of them 🫶

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

note further that attachments are strongly preferred over inlined patches. attachments can be made 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. ok that's very specific but like, do it that way fr fr.

---

⭐ KEYWORDS ⭐

after, channel, coroutine, events, exit, gets, global, green threads, read, threads, update, vwait

---

👑 CATEGORY 👑

Coroutine

---

🌈 COPYRIGHT 🌈

Copyright (c) 2010-2015 Andreas Kupries <andreas_kupries@users.sourceforge.net>

---

and that's the whole page bestie, you ate it 💅 this was tcllib version 1.4, the coroutine(3tcl) manual, and we are so done here. go write some coroutines, you're gonna slay. periodt. 💖✨🎀