135f8bc5fSChristian Brueffer.\" Copyright (c) 2009 Bitgravity Inc 235f8bc5fSChristian Brueffer.\" Written by: Kip Macy <kmacy@FreeBSD.org> 335f8bc5fSChristian Brueffer.\" All rights reserved. 435f8bc5fSChristian Brueffer.\" 535f8bc5fSChristian Brueffer.\" Redistribution and use in source and binary forms, with or without 635f8bc5fSChristian Brueffer.\" modification, are permitted provided that the following conditions 735f8bc5fSChristian Brueffer.\" are met: 835f8bc5fSChristian Brueffer.\" 1. Redistributions of source code must retain the above copyright 935f8bc5fSChristian Brueffer.\" notice, this list of conditions and the following disclaimer. 1035f8bc5fSChristian Brueffer.\" 2. Redistributions in binary form must reproduce the above copyright 1135f8bc5fSChristian Brueffer.\" notice, this list of conditions and the following disclaimer in the 1235f8bc5fSChristian Brueffer.\" documentation and/or other materials provided with the distribution. 1335f8bc5fSChristian Brueffer.\" 1435f8bc5fSChristian Brueffer.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 1535f8bc5fSChristian Brueffer.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 1635f8bc5fSChristian Brueffer.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 1735f8bc5fSChristian Brueffer.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 1835f8bc5fSChristian Brueffer.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 1935f8bc5fSChristian Brueffer.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 2035f8bc5fSChristian Brueffer.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 2135f8bc5fSChristian Brueffer.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 2235f8bc5fSChristian Brueffer.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 2335f8bc5fSChristian Brueffer.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 2435f8bc5fSChristian Brueffer.\" SUCH DAMAGE. 2535f8bc5fSChristian Brueffer.\" 2635f8bc5fSChristian Brueffer.\" $FreeBSD$ 2735f8bc5fSChristian Brueffer.\" 28*063efed2SGleb Smirnoff.Dd September 27, 2012 2935f8bc5fSChristian Brueffer.Dt BUF_RING 9 3035f8bc5fSChristian Brueffer.Os 3135f8bc5fSChristian Brueffer.Sh NAME 3235f8bc5fSChristian Brueffer.Nm buf_ring , 3335f8bc5fSChristian Brueffer.Nm buf_ring_alloc , 3435f8bc5fSChristian Brueffer.Nm buf_ring_free , 3535f8bc5fSChristian Brueffer.Nm buf_ring_enqueue , 3635f8bc5fSChristian Brueffer.Nm buf_ring_dequeue_mc , 3735f8bc5fSChristian Brueffer.Nm buf_ring_dequeue_sc , 3835f8bc5fSChristian Brueffer.Nm buf_ring_count , 3935f8bc5fSChristian Brueffer.Nm buf_ring_empty , 4035f8bc5fSChristian Brueffer.Nm buf_ring_full , 4135f8bc5fSChristian Brueffer.Nm buf_ring_peek , 4235f8bc5fSChristian Brueffer.Nd multi-producer, {single, multi}-consumer lock-less ring buffer 4335f8bc5fSChristian Brueffer.Sh SYNOPSIS 4435f8bc5fSChristian Brueffer.In sys/param.h 4535f8bc5fSChristian Brueffer.In sys/buf_ring.h 4635f8bc5fSChristian Brueffer.Ft struct buf_ring * 4735f8bc5fSChristian Brueffer.Fn buf_ring_alloc "int count" "struct malloc_type *type" "int flags" "struct mtx *sc_lock" 4835f8bc5fSChristian Brueffer.Ft void 4935f8bc5fSChristian Brueffer.Fn buf_ring_free "struct buf_ring *br" "struct malloc_type *type" 5035f8bc5fSChristian Brueffer.Ft int 5135f8bc5fSChristian Brueffer.Fn buf_ring_enqueue "struct buf_ring *br" "void *buf" 5235f8bc5fSChristian Brueffer.Ft void * 5335f8bc5fSChristian Brueffer.Fn buf_ring_dequeue_mc "struct buf_ring *br" 5435f8bc5fSChristian Brueffer.Ft void * 5535f8bc5fSChristian Brueffer.Fn buf_ring_dequeue_sc "struct buf_ring *br" 5635f8bc5fSChristian Brueffer.Ft int 5735f8bc5fSChristian Brueffer.Fn buf_ring_count "struct buf_ring *br" 5835f8bc5fSChristian Brueffer.Ft int 5935f8bc5fSChristian Brueffer.Fn buf_ring_empty "struct buf_ring *br" 6035f8bc5fSChristian Brueffer.Ft int 6135f8bc5fSChristian Brueffer.Fn buf_ring_full "struct buf_ring *br" 6235f8bc5fSChristian Brueffer.Ft void * 6335f8bc5fSChristian Brueffer.Fn buf_ring_peek "struct buf_ring *br" 6435f8bc5fSChristian Brueffer.Sh DESCRIPTION 6535f8bc5fSChristian BruefferThe 6635f8bc5fSChristian Brueffer.Nm 6735f8bc5fSChristian Bruefferfunctions provide a lock-less multi-producer and lock-less multi-consumer as 6835f8bc5fSChristian Bruefferwell as single-consumer ring buffer. 6935f8bc5fSChristian Brueffer.Pp 7035f8bc5fSChristian BruefferThe 7135f8bc5fSChristian Brueffer.Fn buf_ring_alloc 7235f8bc5fSChristian Bruefferfunction is used to allocate a buf_ring ring buffer with 7335f8bc5fSChristian Brueffer.Fa count 7435f8bc5fSChristian Bruefferslots using malloc_type 7535f8bc5fSChristian Brueffer.Fa type 7635f8bc5fSChristian Bruefferand memory flags 7735f8bc5fSChristian Brueffer.Fa flags . 7835f8bc5fSChristian BruefferThe single consumer interface is protected by 7935f8bc5fSChristian Brueffer.Fa sc_lock . 8035f8bc5fSChristian Brueffer.Pp 8135f8bc5fSChristian BruefferThe 8235f8bc5fSChristian Brueffer.Fn buf_ring_free 8335f8bc5fSChristian Bruefferfunction is used to free a buf_ring. 8435f8bc5fSChristian BruefferThe user is responsible for freeing any enqueued items. 8535f8bc5fSChristian Brueffer.Pp 8635f8bc5fSChristian BruefferThe 8735f8bc5fSChristian Brueffer.Fn buf_ring_enqueue 8835f8bc5fSChristian Bruefferfunction is used to enqueue a buffer to a buf_ring. 8935f8bc5fSChristian Brueffer.Pp 9035f8bc5fSChristian BruefferThe 9135f8bc5fSChristian Brueffer.Fn buf_ring_dequeue_mc 9235f8bc5fSChristian Bruefferfunction is a multi-consumer safe way of dequeueing elements from a buf_ring. 9335f8bc5fSChristian Brueffer.Pp 9435f8bc5fSChristian BruefferThe 9535f8bc5fSChristian Brueffer.Fn buf_ring_dequeue_sc 9635f8bc5fSChristian Bruefferfunction is a single-consumer interface to dequeue elements - requiring 9735f8bc5fSChristian Bruefferthe user to serialize accesses with a lock. 9835f8bc5fSChristian Brueffer.Pp 9935f8bc5fSChristian BruefferThe 10035f8bc5fSChristian Brueffer.Fn buf_ring_count 10135f8bc5fSChristian Bruefferfunction returns the number of elements in a buf_ring. 10235f8bc5fSChristian Brueffer.Pp 10335f8bc5fSChristian BruefferThe 10435f8bc5fSChristian Brueffer.Fn buf_ring_empty 10535f8bc5fSChristian Bruefferfunction returns 10635f8bc5fSChristian Brueffer.Dv TRUE 10735f8bc5fSChristian Bruefferif the buf_ring is empty, 10835f8bc5fSChristian Brueffer.Dv FALSE 10935f8bc5fSChristian Bruefferotherwise. 11035f8bc5fSChristian Brueffer.Pp 11135f8bc5fSChristian BruefferThe 11235f8bc5fSChristian Brueffer.Fn buf_ring_full 11335f8bc5fSChristian Bruefferfunction returns 11435f8bc5fSChristian Brueffer.Dv TRUE 11535f8bc5fSChristian Bruefferif no more items can be enqueued, 11635f8bc5fSChristian Brueffer.Dv FALSE 11735f8bc5fSChristian Bruefferotherwise. 11835f8bc5fSChristian Brueffer.Pp 11935f8bc5fSChristian BruefferThe 12035f8bc5fSChristian Brueffer.Fn buf_ring_peek 12135f8bc5fSChristian Bruefferfunction returns a pointer to the last element in the buf_ring if the 12235f8bc5fSChristian Bruefferbuf_ring is not empty, 12335f8bc5fSChristian Brueffer.Dv NULL 12435f8bc5fSChristian Bruefferotherwise. 12535f8bc5fSChristian Brueffer.Sh RETURN VALUES 12635f8bc5fSChristian BruefferThe 12735f8bc5fSChristian Brueffer.Fn buf_ring_enqueue 128*063efed2SGleb Smirnofffunction return 12935f8bc5fSChristian Brueffer.Er ENOBUFS 13035f8bc5fSChristian Bruefferif there are no available slots in the buf_ring. 13135f8bc5fSChristian Brueffer.Sh HISTORY 13235f8bc5fSChristian BruefferThese functions were introduced in 13335f8bc5fSChristian Brueffer.Fx 8.0 . 134