xref: /freebsd/share/man/man9/buf_ring.9 (revision 063efed28c45a81e9f92c69b2fbe1f4f278c8f1a)
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