dnsjit.core.channel(3)

✨ dnsjit.core.channel ✨

okay so bestie, this is a page from the dnsjit Library Functions Manual, and it's literally all about dnsjit.core.channel — the little cutie that sends data to another thread 💌

---

💖 NAME 💖

dnsjit.core.channel — send data to another thread, no cap 🦋

---

🌸 SYNOPSIS 🌸

local chan = require("dnsjit.core.channel").new()
local thr = require("dnsjit.core.thread").new()
thr:start(function(thr)
    local chan = thr:pop()
    local obj = chan:get()
    ...
end)
thr:push(chan)
chan:put(...)
chan:close()
thr:stop()

---

🎀 DESCRIPTION 🎀

So like, a channel is the way you yeet data over to another thread 💅 and the way it does that is by putting a pointer to the data into a wait-free and lock-free ring buffer (that's concurrency kit, for the record). Iconic behaviour, honestly.

The channel runs on the single producer, single consumer model (SPSC), which means there can only be one writer and one reader. One. That's it. Don't get greedy 🙈

🫶 Attributes

• int closed — this is 1 if the channel has been closed. That's the whole vibe check. ✨

🧚 Functions

• Channel.new(capacity) — makes you a brand new Channel 🎉 the optional capacity sets the capacity of the channel (aka the buffer). Heads up: capacity must be a power-of-two greater than or equal to 4. Default capacity is 2048. Slay.
• Channel:log() — hands you back the Log object so you can control logging for this instance or module 📝
• Channel:share() — returns the info you need when sharing this object between threads 👯
• Channel:put(obj) — puts an object into the channel. If the channel is full it will stall and wait until space frees up 😴 and yes, obj is allowed to be nil.
• Channel:put(obj) — tries to put an object into the channel. Returns 0 on success. (yes bestie, the page really does list put twice with the same signature — we're just reporting what it says, no edits 💀)
• Channel:get() — gets an object out of the channel. If the channel is empty it will wait until an object shows up ⏳ Returns nil if the channel is closed, or if a nil object was explicitly put into the channel. Sneaky.
• Channel:try_get() — tries to get an object from the channel. Returns nil if there were no objects to get. No waiting, no drama 🍓
• Channel:size() — returns the number of enqueued objects 🔢
• Channel:full() — returns true when the channel is full 🈵
• Channel:close() — closes the channel. bye bye 👋
• Channel:receive() — returns the C functions and context for receiving objects ⚙️
• Channel:receiver(o) — sets the receiver that objects get passed to. NOTE: the channel keeps no reference of the receiver, so it needs to live as long as the channel does ⚠️ like, keep it alive or things get weird, fr fr.
• Channel:run() — retrieves all objects from the channel and sends them to the receiver 🏃♀️💨

---

💜 SEE ALSO 💜

• dnsjit.core.thread(3) — go read this one too, iykyk 🔥

---

👑 AUTHORS and CONTRIBUTORS 👑

The legends who made this happen:

• Jerry Lundström (DNS-OARC)
• Tomáš Křížek (CZ.NIC)
• Petr Špaček (ISC)

Maintained by DNS-OARC 🫶

https://www.dns-oarc.net/

---

💀 BUGS 💀

Found a problem or want a new feature? Please use:

https://codeberg.org/DNS-OARC/dnsjit/issues

Got a question or need help? Please use:

admin@dns-oarc.net

---

okay that's the whole page bestie, and this lil manual moment came from dnsjit version 1.5.1, dnsjit.core.channel(3), dated way back on 1.5.1 — take care of yourself, hydrate, and may all your ring buffers be lock-free 🌈💖✨