1.\" $OpenBSD: mq_init.9,v 1.8 2016/04/15 05:05:21 dlg 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: April 15 2016 $ 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_purge , 30.Nm mq_drops , 31.Nm mq_set_maxlen , 32.Nm MBUF_QUEUE_INITIALIZER 33.Nd mbuf queue API 34.Sh SYNOPSIS 35.In sys/mbuf.h 36.Ft void 37.Fn mq_init "struct mbuf_queue *mq" "unsigned int maxlen" "int ipl" 38.Ft int 39.Fn mq_enqueue "struct mbuf_queue *mq" "struct mbuf *m" 40.Ft struct mbuf * 41.Fn mq_dequeue "struct mbuf_queue *mq" 42.Ft int 43.Fn mq_enlist "struct mbuf_queue *mq" "struct mbuf_list *ml" 44.Ft void 45.Fn mq_delist "struct mbuf_queue *mq" "struct mbuf_list *ml" 46.Ft struct mbuf * 47.Fn mq_dechain "struct mbuf_queue *mq" 48.Ft unsigned int 49.Fn mq_len "struct mbuf_queue *mq" 50.Ft int 51.Fn mq_empty "struct mbuf_queue *mq" 52.Ft unsigned int 53.Fn mq_purge "struct mbuf_queue *mq" 54.Ft unsigned int 55.Fn mq_drops "struct mbuf_queue *mq" 56.Ft void 57.Fn mq_set_maxlen "struct mbuf_queue *mq" "unsigned int" 58.Ft struct mbuf_queue 59.Fn MBUF_QUEUE_INITIALIZER "unsigned int maxlen" "int ipl" 60.Sh DESCRIPTION 61The mbuf queue API provides implementions of data structures and operations 62for queueing mbufs and lists of mbufs between contexts. 63.Pp 64mbuf_queue data structures provide a superset of the functionality 65available in mbuf_lists, and protect themselves internally with a 66.Xr mutex 9 , 67making them useful for moving mbufs between contexts or subsystems. 68Additionally, mbuf_queues provide a limit on the number of mbufs that 69may be queued. 70.Pp 71mbuf_queue structures support the following functionality: 72.Pp 73.Bl -enum -compact -offset indent 74.It 75Insertion of a new mbuf at the end of the queue. 76.It 77Removal of an mbuf from the head of the queue. 78.It 79Reinsertion of an mbuf at the head of the queue. 80.It 81Removal of the entire chain of mbufs on the queue. 82.It 83Insertion of the mbufs in an mbuf_list at the end of the queue. 84.It 85Removal of all the mbufs on the queue as an mbuf_list. 86.El 87.Bl -tag -width Ds 88.It Fn mq_init "struct mbuf_queue *mq" "unsigned int maxlen" "int ipl" 89Initialises the mbuf queue structure 90.Fa mq . 91The maximum number of mbufs that should be queued is specified with 92.Fa maxlen . 93The highest interrupt priority level the queue will be operated at is 94specified via 95.Fa ipl . 96.It Fn MBUF_QUEUE_INITIALIZER "unsigned int maxlen" "int ipl" 97Initialises an mbuf queue structure declaration. 98The maximum number of mbufs that should be queued is specified with 99.Fa maxlen . 100The highest interrupt priority level the queue will be operated at is 101specified via 102.Fa ipl . 103.It Fn mq_enqueue "struct mbuf_queue *mq" "struct mbuf *m" 104Enqueue mbuf 105.Fa m 106on the end of the 107.Fa mq 108mbuf queue. 109.It Fn mq_dequeue "struct mbuf_queue *mq" 110Dequeue an mbuf from the front of the 111.Fa mq 112mbuf queue. 113.It Fn mq_enlist "struct mbuf_queue *mq" "struct mbuf_list *ml" 114Enqueue all the mbufs on the 115.Fa ml 116mbuf list on to the end of the 117.Fa mq 118mbuf queue. 119Note, the number of mbufs placed on the queue may exceed its maximum length. 120.It Fn mq_delist "struct mbuf_queue *mq" "struct mbuf_list *ml" 121Dequeue all the mbufs on the 122.Fa mq 123mbuf queue on to the 124.Fa ml 125mbuf list. 126.It Fn mq_dechain "struct mbuf_queue *mq" 127Dequeue all mbufs from the 128.Fa mq 129mbuf queue. 130.It Fn mq_len "struct mbuf_queue *mq" 131Return the number of mbufs on the 132.Fa mq 133mbuf queue. 134.It Fn mq_empty "struct mbuf_queue *mq" 135Return if the 136.Fa mq 137mbuf queue is empty. 138.It Fn mq_purge "struct mbuf_queue *mq" 139Free all the mbufs on the 140.Fa mq 141mbuf queue. 142.It Fn mq_drops "struct mbuf_queue *mq" 143Return how many mbufs were dropped and freed by 144.Xr m_freem 9 145if the 146.Fa mq 147mbuf queue was too full. 148.It Fn mq_set_maxlen "struct mbuf_queue *mq" "unsigned int" 149Alter the maximum number of mbufs that should be queued on the 150.Fa mq 151mbuf queue. 152Note, 153.Fn mq_set_maxlen 154will only set a new limit, it will not free any excess mbufs that may 155already exist on the queue. 156.El 157.Sh CONTEXT 158.Fn mq_init , 159.Fn mq_enqueue , 160.Fn mq_dequeue , 161.Fn mq_enlist , 162.Fn mq_delist , 163.Fn mq_dechain , 164.Fn mq_len , 165.Fn mq_empty , 166.Fn mq_purge , 167.Fn mq_drops , 168.Fn mq_set_maxlen , 169and 170.Fn MBUF_QUEUE_INITIALIZER 171can be called during autoconf, from process context, or from interrupt context. 172.Sh RETURN VALUES 173.Fn mq_dequeue 174returns the mbuf that was at the head of its queue. 175If the queue was empty, 176.Dv NULL 177is returned. 178.Pp 179.Fn mq_dechain 180returns all the mbufs that were on its queues via a pointer to an mbuf 181with the chain accessible via m_nextpkt members. 182If the queue was empty, 183.Dv NULL 184is returned. 185.Pp 186.Fn mq_len 187returns the number of mbufs on the queue. 188.Pp 189.Fn mq_empty 190returns a non-zero value if the queue is empty, otherwise 0. 191.Pp 192.Fn mq_enqueue 193returns 0 if the mbuf was successfully queued, or non-zero if the 194mbuf was freed because it would cause the queue to exceed its maximum 195length. 196.Pp 197.Fn mq_enlist 198returns the number of mbufs that were dropped from the list if the 199length of the queue exceeded its maximum length. 200.Pp 201.Fn mq_purge 202returns the number of mbufs that were freed. 203.Pp 204.Fn mq_drops 205returns the number of mbufs that were freed during 206.Fn mq_enqueue 207operations that would have caused the queue to exceed its maximum length. 208.Sh SEE ALSO 209.Xr mbuf 9 , 210.Xr ml_init 9 , 211.Xr mutex 9 212