share/man/man9/buf_ring.9

   1 .\" Copyright (c) 2009 Bitgravity Inc
   2 .\" Written by: Kip Macy <kmacy@FreeBSD.org>
   3 .\" All rights reserved.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer.
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in the
  12 .\"    documentation and/or other materials provided with the distribution.
  13 .\"
  14 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  15 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  16 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  17 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  18 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  19 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  20 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  21 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  22 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  23 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  24 .\" SUCH DAMAGE.
  25 .\"
  26 .\" $FreeBSD$
  27 .\"
  28 .Dd January 30, 2012
  29 .Dt BUF_RING 9
  30 .Os
  31 .Sh NAME
  32 .Nm buf_ring ,
  33 .Nm buf_ring_alloc ,
  34 .Nm buf_ring_free ,
  35 .Nm buf_ring_enqueue ,
  36 .Nm buf_ring_enqueue_bytes ,
  37 .Nm buf_ring_dequeue_mc ,
  38 .Nm buf_ring_dequeue_sc ,
  39 .Nm buf_ring_count ,
  40 .Nm buf_ring_empty ,
  41 .Nm buf_ring_full ,
  42 .Nm buf_ring_peek ,
  43 .Nd multi-producer, {single, multi}-consumer lock-less ring buffer
  44 .Sh SYNOPSIS
  45 .In sys/param.h
  46 .In sys/buf_ring.h
  47 .Ft struct buf_ring *
  48 .Fn buf_ring_alloc "int count" "struct malloc_type *type" "int flags" "struct mtx *sc_lock"
  49 .Ft void
  50 .Fn buf_ring_free "struct buf_ring *br" "struct malloc_type *type"
  51 .Ft int
  52 .Fn buf_ring_enqueue "struct buf_ring *br" "void *buf"
  53 .Ft int
  54 .Fn buf_ring_enqueue_bytes "struct buf_ring *br" "void *buf" "int bytes"
  55 .Ft void *
  56 .Fn buf_ring_dequeue_mc "struct buf_ring *br"
  57 .Ft void *
  58 .Fn buf_ring_dequeue_sc "struct buf_ring *br"
  59 .Ft int
  60 .Fn buf_ring_count "struct buf_ring *br"
  61 .Ft int
  62 .Fn buf_ring_empty "struct buf_ring *br"
  63 .Ft int
  64 .Fn buf_ring_full "struct buf_ring *br"
  65 .Ft void *
  66 .Fn buf_ring_peek "struct buf_ring *br"
  67 .Sh DESCRIPTION
  68 The
  69 .Nm
  70 functions provide a lock-less multi-producer and lock-less multi-consumer as
  71 well as single-consumer ring buffer.
  72 .Pp
  73 The
  74 .Fn buf_ring_alloc
  75 function is used to allocate a buf_ring ring buffer with
  76 .Fa count
  77 slots using malloc_type
  78 .Fa type
  79 and memory flags
  80 .Fa flags .
  81 The single consumer interface is protected by
  82 .Fa sc_lock .
  83 .Pp
  84 The
  85 .Fn buf_ring_free
  86 function is used to free a buf_ring.
  87 The user is responsible for freeing any enqueued items.
  88 .Pp
  89 The
  90 .Fn buf_ring_enqueue
  91 function is used to enqueue a buffer to a buf_ring.
  92 .Pp
  93 The
  94 .Fn buf_ring_enqueue_bytes
  95 function is used to enqueue a buffer to a buf_ring and increment the
  96 number of bytes enqueued by
  97 .Fa bytes .
  98 .Pp
  99 The
 100 .Fn buf_ring_dequeue_mc
 101 function is a multi-consumer safe way of dequeueing elements from a buf_ring.
 102 .Pp
 103 The
 104 .Fn buf_ring_dequeue_sc
 105 function is a single-consumer interface to dequeue elements - requiring
 106 the user to serialize accesses with a lock.
 107 .Pp
 108 The
 109 .Fn buf_ring_count
 110 function returns the number of elements in a buf_ring.
 111 .Pp
 112 The
 113 .Fn buf_ring_empty
 114 function returns
 115 .Dv TRUE
 116 if the buf_ring is empty,
 117 .Dv FALSE
 118 otherwise.
 119 .Pp
 120 The
 121 .Fn buf_ring_full
 122 function returns
 123 .Dv TRUE
 124 if no more items can be enqueued,
 125 .Dv FALSE
 126 otherwise.
 127 .Pp
 128 The
 129 .Fn buf_ring_peek
 130 function returns a pointer to the last element in the buf_ring if the
 131 buf_ring is not empty,
 132 .Dv NULL
 133 otherwise.
 134 .Sh RETURN VALUES
 135 The
 136 .Fn buf_ring_enqueue
 137 and
 138 .Fn buf_ring_enqueue_bytes
 139 functions return
 140 .Er ENOBUFS
 141 if there are no available slots in the buf_ring.
 142 .Sh HISTORY
 143 These functions were introduced in
 144 .Fx 8.0 .