MQ_INIT(9)

🌸 NAME 🌸

okay so this is mq_init(9) from the Kernel Developer's Manual, and it's literally the whole mbuf queue API, bestie. It covers mq_init, mq_enqueue, mq_push, mq_dequeue, mq_enlist, mq_delist, mq_dechain, mq_len, mq_empty, mq_full, mq_hdatalen, mq_purge, mq_drops, mq_set_maxlen, and MBUF_QUEUE_INITIALIZER ✨

---

✨ SYNOPSIS ✨

#include <sys/mbuf.h>

void
mq_init(struct mbuf_queue *mq, unsigned int maxlen, int ipl);

int
mq_enqueue(struct mbuf_queue *mq, struct mbuf *m);

int
mq_push(struct mbuf_queue *mq, struct mbuf *m);

struct mbuf *
mq_dequeue(struct mbuf_queue *mq);

int
mq_enlist(struct mbuf_queue *mq, struct mbuf_list *ml);

void
mq_delist(struct mbuf_queue *mq, struct mbuf_list *ml);

struct mbuf *
mq_dechain(struct mbuf_queue *mq);

unsigned int
mq_len(struct mbuf_queue *mq);

int
mq_empty(struct mbuf_queue *mq);

int
mq_full(struct mbuf_queue *mq);

unsigned int
mq_hdatalen(struct mbuf_queue *mq);

unsigned int
mq_purge(struct mbuf_queue *mq);

unsigned int
mq_drops(struct mbuf_queue *mq);

void
mq_set_maxlen(struct mbuf_queue *mq, unsigned int);

struct mbuf_queue
MBUF_QUEUE_INITIALIZER(unsigned int maxlen, int ipl);

---

💅 DESCRIPTION 💅

The mbuf queue API gives you implementations of data structures and operations for queueing mbufs and lists of mbufs between contexts. It's giving "organized chaos, but make it kernel-safe" 🫶

mbuf_queue data structures provide a superset of the functionality available in mbuf_lists, and they protect themselves internally with a mutex(9), making them useful for moving mbufs between contexts or subsystems. Additionally, mbuf_queues provide a limit on the number of mbufs that may be queued. No cap, that's just the vibe check 💖

🧸 what mbuf_queue structures can do 🧸

These mbuf_queue structures support the following functionality:

1. Insertion of a new mbuf at the end of the queue.
2. Removal of an mbuf from the head of the queue.
3. Reinsertion of an mbuf at the head of the queue.
4. Removal of the entire chain of mbufs on the queue.
5. Insertion of the mbufs in an mbuf_list at the end of the queue.
6. Removal of all the mbufs on the queue as an mbuf_list.

💫 the functions, one by one 💫

• mq_init(struct mbuf_queue *mq, unsigned int maxlen, int ipl) — Initialises the mbuf queue structure mq. The maximum number of mbufs that should be queued is specified with maxlen. The highest interrupt priority level the queue will be operated at is specified via ipl. It's the setup era, main character energy ✨
• MBUF_QUEUE_INITIALIZER(unsigned int maxlen, int ipl) — Initialises an mbuf queue structure declaration. The maximum number of mbufs that should be queued is specified with maxlen. The highest interrupt priority level the queue will be operated at is specified via ipl. Declare it, bestie 🎀
• mq_enqueue(struct mbuf_queue *mq, struct mbuf *m) — Enqueue mbuf m on the end of the mq mbuf queue. If the queue is full then m will be dropped. Sad but true 😭
• mq_push(struct mbuf_queue *mq, struct mbuf *m) — Enqueue mbuf m on the end of the mq mbuf queue. If the queue is full then the mbuf at the head of the queue will be dropped. Out with the old, in with the new 💅
• mq_dequeue(struct mbuf_queue *mq) — Dequeue an mbuf from the front of the mq mbuf queue. Front of the line, no cuts 🦋
• mq_enlist(struct mbuf_queue *mq, struct mbuf_list *ml) — Enqueue all the mbufs on the ml mbuf list on to the end of the mq mbuf queue. Heads up: the number of mbufs placed on the queue may exceed its maximum length 👀
• mq_delist(struct mbuf_queue *mq, struct mbuf_list *ml) — Dequeue all the mbufs on the mq mbuf queue on to the ml mbuf list. Whole queue? Moved. Periodt ✨
• mq_dechain(struct mbuf_queue *mq) — Dequeue all mbufs from the mq mbuf queue. Chain reaction, but make it orderly 🔥
• mq_len(struct mbuf_queue *mq) — Return the number of mbufs on the mq mbuf queue. Length check, but for mbufs 💖
• mq_empty(struct mbuf_queue *mq) — Return if the mq mbuf queue is empty. Is it giving empty? Let's find out 🫶
• mq_full(struct mbuf_queue *mq) — Return if the mq mbuf queue is full. Full house, no vacancies 😭
• mq_hdatalen(struct mbuf_queue *mq) — Return the number of bytes in the packet at the head of the mq mbuf queue. Head packet size reveal 💅
• mq_purge(struct mbuf_queue *mq) — Free all the mbufs on the mq mbuf queue. Clean slate, iconic behavior 🧚
• mq_drops(struct mbuf_queue *mq) — Return how many mbufs were dropped and freed by m_freem(9) if the mq mbuf queue was too full. The drop counter, no cap 💀
• mq_set_maxlen(struct mbuf_queue *mq, unsigned int) — Alter the maximum number of mbufs that should be queued on the mq mbuf queue. Note, mq_set_maxlen() will only set a new limit, it will not free any excess mbufs that may already exist on the queue. It changes the rule, not the population, bestie 🙈

---

🌀 CONTEXT 🌀

mq_init(), mq_enqueue(), mq_push(), mq_dequeue(), mq_enlist(), mq_delist(), mq_dechain(), mq_len(), mq_empty(), mq_full(), mq_purge(), mq_drops(), mq_set_maxlen(), and MBUF_QUEUE_INITIALIZER() can be called during autoconf, from process context, or from interrupt context. Flexible? Obsessed 🌈

---

🎀 RETURN VALUES 🎀

• mq_dequeue() returns the mbuf that was at the head of its queue. If the queue was empty, NULL is returned. Empty queue said "no thoughts, head empty" 😭
• mq_dechain() returns all the mbufs that were on its queues via a pointer to an mbuf with the chain accessible via m_nextpkt members. If the queue was empty, NULL is returned. Whole chain, returned with receipts 🦋
• mq_len() returns the number of mbufs on the queue. Counted, periodt 💅
• mq_empty() returns a non-zero value if the queue is empty, otherwise 0. Empty vibe check ✅
• mq_full() returns a non-zero value if the queue is full, otherwise 0. Full vibe check ✅
• mq_enqueue() returns 0 if the mbuf was successfully queued, or non-zero if the mbuf was freed because it would cause the queue to exceed its maximum length. Success slay, or drop situation 💀
• mq_push() returns 0 if there was space on the queue for the mbuf, or non-zero if the head of the queue was freed to make space for it. Space found, or head said bye 👋
• mq_enlist() returns the number of mbufs that were dropped from the list if the length of the queue exceeded its maximum length. The list got humbled, ngl 😭
• mq_hdatalen() returns the size of a packet on the queue, or 0 if the queue is empty. Size check, bestie 🎀
• mq_purge() returns the number of mbufs that were freed. Freed count, iconic cleanup 🧚
• mq_drops() returns the number of mbufs that were freed during mq_enqueue() operations that would have caused the queue to exceed its maximum length. Drop receipts, fr fr 💅

---

🔗 SEE ALSO 🔗

• mbuf(9)
• ml_init(9)
• mutex(9)

---

cute lil sign-off: this page is Debian-flavoured, dated August 28, 2020, and its footer says MQ_INIT(9) — that's the whole vibe, bestie 💅✨