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 68The 69.Nm 70functions provide a lock-less multi-producer and lock-less multi-consumer as 71well as single-consumer ring buffer. 72.Pp 73The 74.Fn buf_ring_alloc 75function is used to allocate a buf_ring ring buffer with 76.Fa count 77slots using malloc_type 78.Fa type 79and memory flags 80.Fa flags . 81The single consumer interface is protected by 82.Fa sc_lock . 83.Pp 84The 85.Fn buf_ring_free 86function is used to free a buf_ring. 87The user is responsible for freeing any enqueued items. 88.Pp 89The 90.Fn buf_ring_enqueue 91function is used to enqueue a buffer to a buf_ring. 92.Pp 93The 94.Fn buf_ring_enqueue_bytes 95function is used to enqueue a buffer to a buf_ring and increment the 96number of bytes enqueued by 97.Fa bytes . 98.Pp 99The 100.Fn buf_ring_dequeue_mc 101function is a multi-consumer safe way of dequeueing elements from a buf_ring. 102.Pp 103The 104.Fn buf_ring_dequeue_sc 105function is a single-consumer interface to dequeue elements - requiring 106the user to serialize accesses with a lock. 107.Pp 108The 109.Fn buf_ring_count 110function returns the number of elements in a buf_ring. 111.Pp 112The 113.Fn buf_ring_empty 114function returns 115.Dv TRUE 116if the buf_ring is empty, 117.Dv FALSE 118otherwise. 119.Pp 120The 121.Fn buf_ring_full 122function returns 123.Dv TRUE 124if no more items can be enqueued, 125.Dv FALSE 126otherwise. 127.Pp 128The 129.Fn buf_ring_peek 130function returns a pointer to the last element in the buf_ring if the 131buf_ring is not empty, 132.Dv NULL 133otherwise. 134.Sh RETURN VALUES 135The 136.Fn buf_ring_enqueue 137and 138.Fn buf_ring_enqueue_bytes 139functions return 140.Er ENOBUFS 141if there are no available slots in the buf_ring. 142.Sh HISTORY 143These functions were introduced in 144.Fx 8.0 . 145