1.\" $OpenBSD: mq_init.9,v 1.9 2018/02/09 02:26:33 patrick Exp $ 2.\" 3.\" Copyright (c) 2015 David Gwynne <dlg@openbsd.org> 4.\" 5.\" Permission to use, copy, modify, and distribute this software for any 6.\" purpose with or without fee is hereby granted, provided that the above 7.\" copyright notice and this permission notice appear in all copies. 8.\" 9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 16.\" 17.Dd $Mdocdate: February 9 2018 $ 18.Dt MQ_INIT 9 19.Os 20.Sh NAME 21.Nm mq_init , 22.Nm mq_enqueue , 23.Nm mq_dequeue , 24.Nm mq_enlist , 25.Nm mq_delist , 26.Nm mq_dechain , 27.Nm mq_len , 28.Nm mq_empty , 29.Nm mq_full , 30.Nm mq_purge , 31.Nm mq_drops , 32.Nm mq_set_maxlen , 33.Nm MBUF_QUEUE_INITIALIZER 34.Nd mbuf queue API 35.Sh SYNOPSIS 36.In sys/mbuf.h 37.Ft void 38.Fn mq_init "struct mbuf_queue *mq" "unsigned int maxlen" "int ipl" 39.Ft int 40.Fn mq_enqueue "struct mbuf_queue *mq" "struct mbuf *m" 41.Ft struct mbuf * 42.Fn mq_dequeue "struct mbuf_queue *mq" 43.Ft int 44.Fn mq_enlist "struct mbuf_queue *mq" "struct mbuf_list *ml" 45.Ft void 46.Fn mq_delist "struct mbuf_queue *mq" "struct mbuf_list *ml" 47.Ft struct mbuf * 48.Fn mq_dechain "struct mbuf_queue *mq" 49.Ft unsigned int 50.Fn mq_len "struct mbuf_queue *mq" 51.Ft int 52.Fn mq_empty "struct mbuf_queue *mq" 53.Ft int 54.Fn mq_full "struct mbuf_queue *mq" 55.Ft unsigned int 56.Fn mq_purge "struct mbuf_queue *mq" 57.Ft unsigned int 58.Fn mq_drops "struct mbuf_queue *mq" 59.Ft void 60.Fn mq_set_maxlen "struct mbuf_queue *mq" "unsigned int" 61.Ft struct mbuf_queue 62.Fn MBUF_QUEUE_INITIALIZER "unsigned int maxlen" "int ipl" 63.Sh DESCRIPTION 64The mbuf queue API provides implementions of data structures and operations 65for queueing mbufs and lists of mbufs between contexts. 66.Pp 67mbuf_queue data structures provide a superset of the functionality 68available in mbuf_lists, and protect themselves internally with a 69.Xr mutex 9 , 70making them useful for moving mbufs between contexts or subsystems. 71Additionally, mbuf_queues provide a limit on the number of mbufs that 72may be queued. 73.Pp 74mbuf_queue structures support the following functionality: 75.Pp 76.Bl -enum -compact -offset indent 77.It 78Insertion of a new mbuf at the end of the queue. 79.It 80Removal of an mbuf from the head of the queue. 81.It 82Reinsertion of an mbuf at the head of the queue. 83.It 84Removal of the entire chain of mbufs on the queue. 85.It 86Insertion of the mbufs in an mbuf_list at the end of the queue. 87.It 88Removal of all the mbufs on the queue as an mbuf_list. 89.El 90.Bl -tag -width Ds 91.It Fn mq_init "struct mbuf_queue *mq" "unsigned int maxlen" "int ipl" 92Initialises the mbuf queue structure 93.Fa mq . 94The maximum number of mbufs that should be queued is specified with 95.Fa maxlen . 96The highest interrupt priority level the queue will be operated at is 97specified via 98.Fa ipl . 99.It Fn MBUF_QUEUE_INITIALIZER "unsigned int maxlen" "int ipl" 100Initialises an mbuf queue structure declaration. 101The maximum number of mbufs that should be queued is specified with 102.Fa maxlen . 103The highest interrupt priority level the queue will be operated at is 104specified via 105.Fa ipl . 106.It Fn mq_enqueue "struct mbuf_queue *mq" "struct mbuf *m" 107Enqueue mbuf 108.Fa m 109on the end of the 110.Fa mq 111mbuf queue. 112.It Fn mq_dequeue "struct mbuf_queue *mq" 113Dequeue an mbuf from the front of the 114.Fa mq 115mbuf queue. 116.It Fn mq_enlist "struct mbuf_queue *mq" "struct mbuf_list *ml" 117Enqueue all the mbufs on the 118.Fa ml 119mbuf list on to the end of the 120.Fa mq 121mbuf queue. 122Note, the number of mbufs placed on the queue may exceed its maximum length. 123.It Fn mq_delist "struct mbuf_queue *mq" "struct mbuf_list *ml" 124Dequeue all the mbufs on the 125.Fa mq 126mbuf queue on to the 127.Fa ml 128mbuf list. 129.It Fn mq_dechain "struct mbuf_queue *mq" 130Dequeue all mbufs from the 131.Fa mq 132mbuf queue. 133.It Fn mq_len "struct mbuf_queue *mq" 134Return the number of mbufs on the 135.Fa mq 136mbuf queue. 137.It Fn mq_empty "struct mbuf_queue *mq" 138Return if the 139.Fa mq 140mbuf queue is empty. 141.It Fn mq_full "struct mbuf_queue *mq" 142Return if the 143.Fa mq 144mbuf queue is full. 145.It Fn mq_purge "struct mbuf_queue *mq" 146Free all the mbufs on the 147.Fa mq 148mbuf queue. 149.It Fn mq_drops "struct mbuf_queue *mq" 150Return how many mbufs were dropped and freed by 151.Xr m_freem 9 152if the 153.Fa mq 154mbuf queue was too full. 155.It Fn mq_set_maxlen "struct mbuf_queue *mq" "unsigned int" 156Alter the maximum number of mbufs that should be queued on the 157.Fa mq 158mbuf queue. 159Note, 160.Fn mq_set_maxlen 161will only set a new limit, it will not free any excess mbufs that may 162already exist on the queue. 163.El 164.Sh CONTEXT 165.Fn mq_init , 166.Fn mq_enqueue , 167.Fn mq_dequeue , 168.Fn mq_enlist , 169.Fn mq_delist , 170.Fn mq_dechain , 171.Fn mq_len , 172.Fn mq_empty , 173.Fn mq_full , 174.Fn mq_purge , 175.Fn mq_drops , 176.Fn mq_set_maxlen , 177and 178.Fn MBUF_QUEUE_INITIALIZER 179can be called during autoconf, from process context, or from interrupt context. 180.Sh RETURN VALUES 181.Fn mq_dequeue 182returns the mbuf that was at the head of its queue. 183If the queue was empty, 184.Dv NULL 185is returned. 186.Pp 187.Fn mq_dechain 188returns all the mbufs that were on its queues via a pointer to an mbuf 189with the chain accessible via m_nextpkt members. 190If the queue was empty, 191.Dv NULL 192is returned. 193.Pp 194.Fn mq_len 195returns the number of mbufs on the queue. 196.Pp 197.Fn mq_empty 198returns a non-zero value if the queue is empty, otherwise 0. 199.Pp 200.Fn mq_full 201returns a non-zero value if the queue is full, otherwise 0. 202.Pp 203.Fn mq_enqueue 204returns 0 if the mbuf was successfully queued, or non-zero if the 205mbuf was freed because it would cause the queue to exceed its maximum 206length. 207.Pp 208.Fn mq_enlist 209returns the number of mbufs that were dropped from the list if the 210length of the queue exceeded its maximum length. 211.Pp 212.Fn mq_purge 213returns the number of mbufs that were freed. 214.Pp 215.Fn mq_drops 216returns the number of mbufs that were freed during 217.Fn mq_enqueue 218operations that would have caused the queue to exceed its maximum length. 219.Sh SEE ALSO 220.Xr mbuf 9 , 221.Xr ml_init 9 , 222.Xr mutex 9 223