1 files changed, 133 insertions, 0 deletions
diff --git a/share/man/man9/buf_ring.9 b/share/man/man9/buf_ring.9
new file mode 100644
index 0000000..95b3a3d
--- /dev/null
+++ b/share/man/man9/buf_ring.9
@@ -0,0 +1,133 @@
+.\" Copyright (c) 2009 Bitgravity Inc
+.\" Written by: Kip Macy <kmacy@FreeBSD.org>
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.\" $FreeBSD$
+.\"
+.Dd September 27, 2012
+.Dt BUF_RING 9
+.Os
+.Sh NAME
+.Nm buf_ring ,
+.Nm buf_ring_alloc ,
+.Nm buf_ring_free ,
+.Nm buf_ring_enqueue ,
+.Nm buf_ring_dequeue_mc ,
+.Nm buf_ring_dequeue_sc ,
+.Nm buf_ring_count ,
+.Nm buf_ring_empty ,
+.Nm buf_ring_full ,
+.Nm buf_ring_peek ,
+.Nd multi-producer, {single, multi}-consumer lock-less ring buffer
+.Sh SYNOPSIS
+.In sys/param.h
+.In sys/buf_ring.h
+.Ft struct buf_ring *
+.Fn buf_ring_alloc "int count" "struct malloc_type *type" "int flags" "struct mtx *sc_lock"
+.Ft void
+.Fn buf_ring_free "struct buf_ring *br" "struct malloc_type *type"
+.Ft int
+.Fn buf_ring_enqueue "struct buf_ring *br" "void *buf"
+.Ft void *
+.Fn buf_ring_dequeue_mc "struct buf_ring *br"
+.Ft void *
+.Fn buf_ring_dequeue_sc "struct buf_ring *br"
+.Ft int
+.Fn buf_ring_count "struct buf_ring *br"
+.Ft int
+.Fn buf_ring_empty "struct buf_ring *br"
+.Ft int
+.Fn buf_ring_full "struct buf_ring *br"
+.Ft void *
+.Fn buf_ring_peek "struct buf_ring *br"
+.Sh DESCRIPTION
+The
+.Nm
+functions provide a lock-less multi-producer and lock-less multi-consumer as
+well as single-consumer ring buffer.
+.Pp
+The
+.Fn buf_ring_alloc
+function is used to allocate a buf_ring ring buffer with
+.Fa count
+slots using malloc_type
+.Fa type
+and memory flags
+.Fa flags .
+The single consumer interface is protected by
+.Fa sc_lock .
+.Pp
+The
+.Fn buf_ring_free
+function is used to free a buf_ring.
+The user is responsible for freeing any enqueued items.
+.Pp
+The
+.Fn buf_ring_enqueue
+function is used to enqueue a buffer to a buf_ring.
+.Pp
+The
+.Fn buf_ring_dequeue_mc
+function is a multi-consumer safe way of dequeueing elements from a buf_ring.
+.Pp
+The
+.Fn buf_ring_dequeue_sc
+function is a single-consumer interface to dequeue elements - requiring
+the user to serialize accesses with a lock.
+.Pp
+The
+.Fn buf_ring_count
+function returns the number of elements in a buf_ring.
+.Pp
+The
+.Fn buf_ring_empty
+function returns
+.Dv TRUE
+if the buf_ring is empty,
+.Dv FALSE
+otherwise.
+.Pp
+The
+.Fn buf_ring_full
+function returns
+.Dv TRUE
+if no more items can be enqueued,
+.Dv FALSE
+otherwise.
+.Pp
+The
+.Fn buf_ring_peek
+function returns a pointer to the last element in the buf_ring if the
+buf_ring is not empty,
+.Dv NULL
+otherwise.
+.Sh RETURN VALUES
+The
+.Fn buf_ring_enqueue
+function return
+.Er ENOBUFS
+if there are no available slots in the buf_ring.
+.Sh HISTORY
+These functions were introduced in
+.Fx 8.0 .