BUFQ_INIT(9)

💅 BUFQ_INIT — bestie's guide to buf queues

ok so this is BUFQ_INIT(9) from the Kernel Developer's Manual, and honestly? it's giving "the entire I/O scheduling saga in one page." buckle up 🎀

---

✨ NAME ✨

bufq_init, bufq_destroy, bufq_queue, bufq_dequeue, bufq_peek, bufq_drain — buf queues. that's the whole vibe. a little family of functions that manage queues of bufs. 💖

---

🌸 SYNOPSIS 🌸

#include <sys/buf.h>

int
bufq_init(struct bufq *bufq, int type);

void
bufq_destroy(struct bufq *bufq);

void
bufq_queue(struct bufq *bufq, struct buf *bp);

struct buf *
bufq_dequeue(struct bufq *bufq);

int
bufq_peek(struct bufq *bufq);

void
bufq_drain(struct bufq *bufq);

---

🦋 DESCRIPTION 🦋

so the bufq API is literally the whole queueing-and-scheduling situation for I/O operations on disk devices. it hands you multiple scheduling algorithms, all wrapped up in one API. iconic behavior tbh 👑

important vibe check: it's your job — the disk device driver's job — to provide pre-allocated bufq structures. the API is not gonna do it for you, bestie. you bring the bufq, it brings the scheduling. 🤝

bufq_init() initialises the bufq structure and allocates whatever state the scheduling algorithm needs, and that algorithm is picked by the type argument. ✨

the type argument to bufq_init() can be one of these scheduling algorithms:

• BUFQ_FIFO — a simple First-In First-Out queue. no notes, it's exactly what it says. 🍓
• BUFQ_NSCAN — takes batches of "N" bufs from the queue and sorts them for optimal head movement. fancy! 🔥
• BUFQ_DEFAULT — this currently aliases BUFQ_NSCAN. so like, it's BUFQ_NSCAN in a lil disguise. 🎀

bufq_destroy() frees any state that was used by the scheduler. cleanup queen. 🧹

bufq_queue() is how you add the buf specified by bp to the bufq queue. drop it in, it's queued. 💅

bufq_dequeue() gets you the next buf the bufq has scheduled to be serviced by a disk. heads up: the buf gets removed from the queue. so like, it's yours now, it's not coming back. 😭

bufq_peek() lets the caller find out if there are more bufs queued on bufq — and the whole point is it does this without modifying the list of bufs. no touchy, just looky 👀

bufq_drain() is a convenience function for devices that have detached. it removes all the bufs currently queued on bufq, marks them as failed with an ENXIO error, and returns them to the block layer via biodone(9). it's giving "we're closing, everybody out." 🚪

---

🫶 CONTEXT 🫶

bufq_init() and bufq_destroy() can be called during autoconf, or from process context. 🌈

bufq_queue, bufq_dequeue, bufq_peek, and bufq_drain can be called during autoconf, from process context, or from interrupt context. flexible icons ⭐

---

👑 RETURN VALUES 👑

bufq_init() will return 0 on success, or an error code as per errno(2). slay when it's 0, check your errno when it's not 💀

bufq_dequeue() returns the next buf that is scheduled to be serviced by the disk. and NULL is returned if there are no bufs available on the queue. empty queue, empty hands 🙈

bufq_peek() returns 1 if there are bufs available to be scheduled on the disk, otherwise 0. a simple little yes/no, we love a binary 🎀

---

🔍 SEE ALSO 🔍

errno(2), autoconf(9), biodone(9), disk(9)

go read those too, iykwim 💜

---

📜 HISTORY 📜

the bufq API was written by Thordur I. Bjornsson and David Gwynne <dlg@openbsd.org>. the bufq API first appeared in OpenBSD 4.8 and finally succeeded in fully replacing disksort in OpenBSD 5.5. a real glow-up era ✨🔥

---

and that's the page, bestie 🎀 this Debian build is dated May 17, 2025 — go forth and schedule those bufs responsibly 💖