TQUEUE(3tcl)

💖 transfer::copy::queue — Queued transfers 💖

okay so bestie, welcome to transfer::copy::queue(3tcl), a lil page from the tcllib manual, section 3tcl. This is the ✨queue your transfers✨ module and honestly it's giving traffic control for your channel. Buckle up 🎀

---

🌸 SYNOPSIS 🌸

First things first, the prerequisites. You gotta have these packages, no cap:

package require Tcl 8.5 9

package require snit ?1.0?

package require struct::queue ?1.4?

package require transfer::copy ?0.3?

package require transfer::copy::queue ?0.2?

Then the actual vibes:

transfer::copy::queue objectName outchannel ?options...?

objectName method ?arg arg ...?

objectName destroy

objectName busy

objectName pending

objectName put request

---

🦋 DESCRIPTION 🦋

So this package hands you objects that serialize transfer requests for one single channel, using a fifo queue. Think of it as a bouncer at the club door but for data 💅

Accumulated requests get executed in order of entrance. The very first request that reaches an idle object is the one that kicks off execution in general. And here's the cute part: you can keep adding new requests while the object is already active — they just get defered until every request that came in before them has been completed successfully. queued girlies stay queued ✨

⚠️ When a request causes a transfer error, execution STOPS. All the requests coming after it are not served. And right now, that means their completion callbacks are never triggered at all. 😭

NOTE: Not triggering the completion callbacks of the unserved requests after an error stops the queue object is something the author is not fully sure makes sense. It forces the user of the queue to remember the callbacks as well and run them, because otherwise everything in the system that depends on getting a notification about the status of a request will just... hang in the air 🫠. The author is slowly convincing themselves that it's more sensible to trigger the relevant completion callbacks with an error message about the queue abort, and 0 bytes transfered. Noted. Iconic self-awareness honestly.

---

All transfer requests are shaped like this:

{type data options...}

where type is one of chan or string, and data specifies the information to transfer. 👀

• for chan, data is the handle of the channel containing the actual information to transfer
• for string, data contains the information to transfer directly

The options are a list of them and their values, and they're the same ones the low-level copy operations of the package transfer::copy accept. And here's a lil glow-up trick: if you just prepend the request with transfer::copy::do and slip a channel handle in between data and options, it transforms from a pure data structure into a command whose evaluation will perform the request. main character transformation fr fr 💫

---

👑 API 👑

🌈 PACKAGE COMMANDS 🌈

• transfer::copy::queue objectName outchannel ?options...? — this command creates a brand new queue object for managing the channel outchannel, with an associated Tcl command whose name is objectName. That object command is explained in full detail down in the Object command and Object methods sections. The set of supported options lives in the Options section. 💖

The object command gets created under the current namespace if objectName isn't fully qualified, and in the specified namespace otherwise. The fully qualified name of the object command is returned as the result of the command. slay 🫶

🧚 OBJECT COMMAND 🧚

All objects created by the ::transfer::copy::queue command have this general form:

• objectName method ?arg arg ...? — the method method and its arg'uments determine the exact behavior of the command. See the Object methods section for the detailed specifications.

💜 OBJECT METHODS 💜

• objectName destroy — this method destroys the object. Doing so while the object is busy will cause errors later on, when the currently executed request completes and tries to access the now missing data structures of the destroyed object. 💀 so like, don't do that.
• objectName busy — this method returns a boolean value telling us if the object is currently serving a request (i.e. busy, value True), or not (i.e. idle, value False). vibe check on the object basically ✨
• objectName pending — this method returns the number of requests currently waiting in the queue for their execution. A request that's currently being served is not counted as waiting. okay periodt 🔥
• objectName put request — this method enters the transfer request into the object's queue of waiting requests. If the object is idle, it becomes busy and immediately services the request. Otherwise, servicing the new request gets defered until all preceding requests have been served. 🎀

---

✨ OPTIONS ✨

The only option known is -on-status-change. It's optional and defaults to the empty list, which disables the reporting of status changes. Otherwise its argument is a command prefix that gets invoked whenever the internal status of the object changed. 💅

The callback is invoked with two additional arguments: the result of the methods pending and busy, in this order. This lets any user easily know, for example, when the object has processed all outstanding requests. so helpful bestie 🫶

---

🍓 USE 🍓

A possible application of this package and class is inside an HTTP 1.1 server, managing the results that are waiting for transfer to the client. 🌐

But it should be noted 👀 that in this application the system also needs an additional data structure which keeps track of outstanding results, since they may come back in a different order than the requests from the client. That structure releases them to the actual queue in the proper order. teamwork makes the dream work fr fr 🌈

---

😭 BUGS, IDEAS, FEEDBACK 😭

This document, and the package it describes, will undoubtedly contain bugs and other problems. Please report such in the category transfer 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 love feedback 💖

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. iykyk 💅

---

⭐ KEYWORDS ⭐

channel, copy, queue, transfer

---

🌸 CATEGORY 🌸

Transfer module

---

🎀 COPYRIGHT 🎀

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

---

and that's the whole page bestie!! 🦋 this was tcllib version 0.2 of transfer::copy::queue(3tcl) — go forth and queue responsibly, no cap 💜✨