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 September 27, 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_dequeue_mc ,
  37 .Nm buf_ring_dequeue_sc ,
  38 .Nm buf_ring_count ,
  39 .Nm buf_ring_empty ,
  40 .Nm buf_ring_full ,
  41 .Nm buf_ring_peek ,
  42 .Nd multi-producer, {single, multi}-consumer lock-less ring buffer
  43 .Sh SYNOPSIS
  44 .In sys/param.h
  45 .In sys/buf_ring.h
  46 .Ft struct buf_ring *
  47 .Fn buf_ring_alloc "int count" "struct malloc_type *type" "int flags" "struct mtx *sc_lock"
  48 .Ft void
  49 .Fn buf_ring_free "struct buf_ring *br" "struct malloc_type *type"
  50 .Ft int
  51 .Fn buf_ring_enqueue "struct buf_ring *br" "void *buf"
  52 .Ft void *
  53 .Fn buf_ring_dequeue_mc "struct buf_ring *br"
  54 .Ft void *
  55 .Fn buf_ring_dequeue_sc "struct buf_ring *br"
  56 .Ft int
  57 .Fn buf_ring_count "struct buf_ring *br"
  58 .Ft int
  59 .Fn buf_ring_empty "struct buf_ring *br"
  60 .Ft int
  61 .Fn buf_ring_full "struct buf_ring *br"
  62 .Ft void *
  63 .Fn buf_ring_peek "struct buf_ring *br"
  64 .Sh DESCRIPTION
  65 The
  66 .Nm
  67 functions provide a lock-less multi-producer and lock-less multi-consumer as
  68 well as single-consumer ring buffer.
  69 .Pp
  70 The
  71 .Fn buf_ring_alloc
  72 function is used to allocate a buf_ring ring buffer with
  73 .Fa count
  74 slots using malloc_type
  75 .Fa type
  76 and memory flags
  77 .Fa flags .
  78 The single consumer interface is protected by
  79 .Fa sc_lock .
  80 .Pp
  81 The
  82 .Fn buf_ring_free
  83 function is used to free a buf_ring.
  84 The user is responsible for freeing any enqueued items.
  85 .Pp
  86 The
  87 .Fn buf_ring_enqueue
  88 function is used to enqueue a buffer to a buf_ring.
  89 .Pp
  90 The
  91 .Fn buf_ring_dequeue_mc
  92 function is a multi-consumer safe way of dequeueing elements from a buf_ring.
  93 .Pp
  94 The
  95 .Fn buf_ring_dequeue_sc
  96 function is a single-consumer interface to dequeue elements - requiring
  97 the user to serialize accesses with a lock.
  98 .Pp
  99 The
 100 .Fn buf_ring_count
 101 function returns the number of elements in a buf_ring.
 102 .Pp
 103 The
 104 .Fn buf_ring_empty
 105 function returns
 106 .Dv TRUE
 107 if the buf_ring is empty,
 108 .Dv FALSE
 109 otherwise.
 110 .Pp
 111 The
 112 .Fn buf_ring_full
 113 function returns
 114 .Dv TRUE
 115 if no more items can be enqueued,
 116 .Dv FALSE
 117 otherwise.
 118 .Pp
 119 The
 120 .Fn buf_ring_peek
 121 function returns a pointer to the last element in the buf_ring if the
 122 buf_ring is not empty,
 123 .Dv NULL
 124 otherwise.
 125 .Sh RETURN VALUES
 126 The
 127 .Fn buf_ring_enqueue
 128 function return
 129 .Er ENOBUFS
 130 if there are no available slots in the buf_ring.
 131 .Sh HISTORY
 132 These functions were introduced in
 133 .Fx 8.0 .