tevent_queue_tutorial(3)

🎀 NAME 🎀

tevent_queue_tutorial — bestie, this is the tevent_queue tutorial, and it's in section 3 of the library functions manual 💅

---

✨ Introduction ✨

okay so picture this: a tevent_queue is what you use to queue up async requests that have to be serialized. like, they cannot overlap, they gotta take turns, no cutting in line 🚶♀️🚶♀️🚶♀️

the classic example? writing buffers into a socket. that has to be serialized, periodt. because writing a big lump of data into a socket can need multiple write(2) or send(2) system calls — it's not always one and done 😭

and here's the thing: if more than one async request is outstanding, all trying to write large buffers into a socket, then every request must individually be completed before the next one begins — even if multiple syscalls are required for it. no interleaving, no mixing, not ever 🙅♀️

to make that happen, every socket gets assigned a tevent_queue struct. one queue per socket, that's the vibe 🫶

---

🦋 how you actually make one of these 🦋

creating a serialized async request follows the usual convention: you return a tevent_req structure with an embedded state structure. iconic, love that for us ✨

but here's the plot twist — to serialize the work that the request is about to do, instead of directly starting or doing that work, you have to call tevent_queue_add. that's the move 💅

then, when it's finally time for the serialized async request to do its thing, the trigger callback function that you gave to tevent_queue_add gets called. in the writing-to-a-socket example, that trigger fires when the write request is allowed to begin accessing the socket 🔥

---

🌸 the lore: how this engine works behind the scenes 🌸

okay bestie, sit down, because this part is lowkey genius 🧠✨

• when the queue is empty, tevent_queue_add schedules an immediate call to the trigger callback.
• the trigger callback starts its work — and it'll probably do that by starting other async subrequests.
• while those async subrequests are busy working, more requests can accumulate in the queue via tevent_queue_add. they just pile up, patiently, like a group chat when you're asleep 😴
• and here's the wild part: there is no function to explicitly trigger the next waiter in line. none. doesn't exist. and yet?? it still works 💀
• because when the active request in the queue is done, it gets destroyed by talloc_free.
• and talloc_free of a serialized async request that had been added to a queue will trigger the next request in the queue — via a talloc destructor attached to a child of the serialized request. yeah. a destructor. doing queue management. main character energy fr fr 👑

so that's how the queue stays busy whenever an async request finishes. it's giving "the next one up, automatically" 🌈

---

💖 Example 💖

Metze: Please add a code example here.

(that's it. that's the whole example section. we're waiting on Metze, bestie 🙈 if you got a code example, the queue is literally right there — no pressure tho 🍓)

---

and that's the whole page!! 🌟 this was tevent_queue_tutorial(3) from the tevent crew, Version 0.9.8 — go serialize something responsibly, ily, bye bestie 💜🦋✨