share/man/man9/pcq.9

   1 .\"     $NetBSD: pcq.9,v 1.3 2010/01/08 12:12:49 rmind 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
  51 The machine-independent
  52 .Nm
  53 interface provides lockless producer/consumer queues.
  54 A queue
  55 .Po
  56 .Vt pcq_t
  57 .Pc
  58 allows multiple writers
  59 .Pq producers ,
  60 but only a single reader
  61 .Pq consumer .
  62 The consumer is expected to be protected by a lock that covers
  63 the structure that the
  64 .Vt pcq_t
  65 is embedded into
  66 .Po
  67 e.g., socket lock, ifnet hwlock
  68 .Pc .
  69 These queues operate in a first-in, first-out
  70 .Pq FIFO
  71 manner.
  72 The act of inserting or removing an item from a
  73 .Vt pcq_t
  74 does not modify the item in any way.
  75 .Nm
  76 does 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"
  81 Create a queue that can store at most
  82 .Fa maxlen
  83 items at one time.
  84 .Fa kmflags
  85 should be either
  86 .Dv KM_SLEEP ,
  87 if
  88 .Fn pcq_create
  89 is allowed to sleep until resources are available, or
  90 .Dv KM_NOSLEEP
  91 if it should return
  92 .Dv NULL
  93 immediately, if resources are unavailable.
  94 .It Fn pcq_destroy "pcq"
  95 Free the resources held by
  96 .Fa pcq .
  97 .It Fn pcq_get "pcq"
  98 Remove the next item to be consumed from the queue and return
  99 it.
 100 If the queue is empty,
 101 return
 102 .Dv NULL .
 103 .It Fn pcq_maxitems "pcq"
 104 Return the maximum number of items that the queue can store at
 105 any one time.
 106 .It Fn pcq_peek "pcq"
 107 Return the next item to be consumed from the queue but do not remove
 108 it from the queue.
 109 If the queue is empty,
 110 return
 111 .Dv NULL .
 112 .It Fn pcq_put "pcq" "item"
 113 Place an item at the end of the queue.
 114 If there is no room in the queue for the item, return
 115 .Dv false ;
 116 otherwise, return
 117 .Dv true .
 118 The item must not have the value of
 119 .Dv NULL .
 120 .El
 121 .Sh CODE REFERENCES
 122 This section describes places within the
 123 .Nx
 124 source tree where actual code implementing the
 125 .Nm
 126 interface
 127 can be found.
 128 All pathnames are relative to
 129 .Pa /usr/src .
 130 .Pp
 131 The
 132 .Nm
 133 interface is implemented within the file
 134 .Pa sys/kern/subr_pcq.c .
 135 .\" .Sh EXAMPLES
 136 .Sh SEE ALSO
 137 .Xr atomic_ops 3 ,
 138 .Xr queue 9
 139 .Sh HISTORY
 140 The
 141 .Nm
 142 interface first appeared in
 143 .Nx 6.0 .
 144 .Sh AUTHORS
 145 .An Matt Thomas Aq matt@NetBSD.org
 146 .\" .Sh CAVEATS
 147 .\" .Sh BUGS
 148 .\" .Sh SECURITY CONSIDERATIONS