1.\" $NetBSD: pcq.9,v 1.5 2010/12/02 12:54:13 wiz Exp $ 2.\" 3.\" Copyright (c) 2010 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Matt Thomas. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28.\" POSSIBILITY OF SUCH DAMAGE. 29.\" 30.Dd January 8, 2010 31.Dt PCQ 9 32.Os 33.Sh NAME 34.Nm pcq 35.Nd producer/consumer queue 36.Sh SYNOPSIS 37.In sys/pcq.h 38.Ft pcq_t * 39.Fn pcq_create "size_t maxlen" "km_flags_t kmflags" 40.Ft void 41.Fn pcq_destroy "pcq_t *pcq" 42.Ft void * 43.Fn pcq_get "pcq_t *pcq" 44.Ft size_t 45.Fn pcq_maxitems "pcq_t *pcq" 46.Ft void * 47.Fn pcq_peek "pcq_t *pcq" 48.Ft bool 49.Fn pcq_put "pcq_t *pcq" "void *item" 50.Sh DESCRIPTION 51The machine-independent 52.Nm 53interface provides lockless producer/consumer queues. 54A queue 55.Po 56.Vt pcq_t 57.Pc 58allows multiple writers 59.Pq producers , 60but only a single reader 61.Pq consumer . 62The consumer is expected to be protected by a lock that covers 63the structure that the 64.Vt pcq_t 65is embedded into 66.Po 67e.g., socket lock, ifnet hwlock 68.Pc . 69These queues operate in a first-in, first-out 70.Pq FIFO 71manner. 72The act of inserting or removing an item from a 73.Vt pcq_t 74does not modify the item in any way. 75.Nm 76does not prevent an item from being inserted multiple times into a single 77.Vt pcq_t . 78.Sh FUNCTIONS 79.Bl -tag -width compact 80.It Fn pcq_create "maxlen" "kmflags" 81Create a queue that can store at most 82.Fa maxlen 83items at one time. 84.Fa kmflags 85should be either 86.Dv KM_SLEEP , 87if 88.Fn pcq_create 89is allowed to sleep until resources are available, or 90.Dv KM_NOSLEEP 91if it should return 92.Dv NULL 93immediately, if resources are unavailable. 94.It Fn pcq_destroy "pcq" 95Free the resources held by 96.Fa pcq . 97.It Fn pcq_get "pcq" 98Remove the next item to be consumed from the queue and return 99it. 100If the queue is empty, 101return 102.Dv NULL . 103.It Fn pcq_maxitems "pcq" 104Return the maximum number of items that the queue can store at 105any one time. 106.It Fn pcq_peek "pcq" 107Return the next item to be consumed from the queue but do not remove 108it from the queue. 109If the queue is empty, 110return 111.Dv NULL . 112.It Fn pcq_put "pcq" "item" 113Place an item at the end of the queue. 114If there is no room in the queue for the item, return 115.Dv false ; 116otherwise, return 117.Dv true . 118The item must not have the value of 119.Dv NULL . 120.El 121.Sh CODE REFERENCES 122The 123.Nm 124interface is implemented within the file 125.Pa sys/kern/subr_pcq.c . 126.\" .Sh EXAMPLES 127.Sh SEE ALSO 128.Xr atomic_ops 3 , 129.Xr queue 9 130.Sh HISTORY 131The 132.Nm 133interface first appeared in 134.Nx 6.0 . 135.Sh AUTHORS 136.An Matt Thomas Aq matt@NetBSD.org 137.\" .Sh CAVEATS 138.\" .Sh BUGS 139.\" .Sh SECURITY CONSIDERATIONS 140