MQ_INIT(9) | Kernel Developer's Manual | MQ_INIT(9)

# NAME

`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`, `MBUF_QUEUE_INITIALIZER` — mbuf queue API

# 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 provides implementations of data structures and operations for queueing mbufs and lists of mbufs between contexts.

mbuf_queue data structures provide a superset of the functionality available in mbuf_lists, and 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.

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.

`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.
`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.
`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.
`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.
`mq_dequeue`(struct mbuf_queue *mq)
  Dequeue an mbuf from the front of the mq mbuf queue.
`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. Note, 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.
`mq_dechain`(struct mbuf_queue *mq)
  Dequeue all mbufs from the mq mbuf queue.
`mq_len`(struct mbuf_queue *mq)
  Return the number of mbufs on the mq mbuf queue.
`mq_empty`(struct mbuf_queue *mq)
  Return if the mq mbuf queue is empty.
`mq_full`(struct mbuf_queue *mq)
  Return if the mq mbuf queue is full.
`mq_hdatalen`(struct mbuf_queue *mq)
  Return the number of bytes in the packet at the head of the mq mbuf queue.
`mq_purge`(struct mbuf_queue *mq)
  Free all the mbufs on the mq mbuf queue.
`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.
`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.

# 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.

# RETURN VALUES

`mq_dequeue`() returns the mbuf that was at the head of its queue. If the queue was empty, `NULL` is returned.

`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.

`mq_len`() returns the number of mbufs on the queue.

`mq_empty`() returns a non-zero value if the queue is empty, otherwise 0.

`mq_full`() returns a non-zero value if the queue is full, otherwise 0.

`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.

`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.

`mq_enlist`() returns the number of mbufs that were dropped from the list if the length of the queue exceeded its maximum length.

`mq_hdatalen`() returns the size of a packet on the queue, or 0 if the queue is empty.

`mq_purge`() returns the number of mbufs that were freed.

`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.

# SEE ALSO

mbuf(9), ml_init(9), mutex(9)

August 28, 2020 | Debian