MQ_INIT(9)

NAME
mq_init, mq_enqueue, mq_dequeue, mq_enlist, mq_delist, mq_dechain, mq_filter, mq_len, mq_empty, 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);
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);
struct mbuf *
mq_filter(struct mbuf_queue *mq, int (*filter)(void *, struct mbuf *), void *context);
unsigned int
mq_len(struct mbuf_queue *mq);
int
mq_empty(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 implementions 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.

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_filter(
    struct mbuf_queue *mq, int (*filter)(void *, struct mbuf *), void *context) Iterates over the mbufs on the mq mbuf queue, passing each of them to the filter function. If the filter returns non-zero, the packet is removed from the mq mbuf queue to be returned as part of an mbuf chain by mq_filter(). context is passed as the first argument to each call of filter.

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_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_dequeue(), mq_enlist(), mq_delist(), mq_dechain(), mq_len(), mq_empty(), 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_filter() returns the mbufs that were successfully matched by the filter function on the queue via a pointer to a chain of mbufs. If no packets matched the filter, 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_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_enlist() returns the number of mbufs that were dropped from the list if the length of the queue exceeded its maximum length.

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)