2 Memory-mapped ringbuffer
3 Derived from jack/ringbuffer.h
5 This program is free software; you can redistribute it and/or modify
6 it under the terms of the GNU Lesser General Public License as published by
7 the Free Software Foundation; either version 2.1 of the License, or
8 (at your option) any later version.
10 This program is distributed in the hope that it will be useful,
11 but WITHOUT ANY WARRANTY; without even the implied warranty of
12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 GNU Lesser General Public License for more details.
15 You should have received a copy of the GNU Lesser General Public License
16 along with this program; if not, write to the Free Software
17 Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
20 Copyright (C) 2000 Paul Davis
21 Copyright (C) 2003 Rohan Drape
24 Copyright (C) 2004 by Frank Brickle, AB2KT and Bob McGwier, N4HY
30 #include <sys/types.h>
45 /* Sets up a ringbuffer data structure of a specified size
46 * in pre-allocated memory.
47 * sz is requested ringbuffer size in bytes,
48 * MUST be a power of 2.
49 * pre-allocated memory must be large enough to
50 * accommodate (ringb header + stipulated memory size).
51 * return a pointer to a new ringb_t, if successful,
54 extern ringb_t *ringb_create(char *usemem, size_t sz2);
57 * There is no corresponding 'free' function
58 * since memory is all pre-allocated
61 //void ringb_free(ringb_t *rb);
63 /* Fill a data structure with a description of the current readable
64 * data held in the ringbuffer. This description is returned in a two
65 * element array of ringb_data_t. Two elements are needed
66 * because the data to be read may be split across the end of the
69 * The first element will always contain a valid len field, which
70 * may be zero or greater. If the len field is non-zero, then data
71 * can be read in a contiguous fashion using the address given in the
72 * corresponding @a buf field.
74 * If the second element has a non-zero len field, then a second
75 * contiguous stretch of data can be read from the address given in
76 * its corresponding buf field.
78 * rb a pointer to the ringbuffer structure.
79 * vec a pointer to a 2 element array of ringb_data_t. */
81 extern void ringb_get_read_vector(const ringb_t *rb, ringb_data_t *vec);
83 /* Fill a data structure with a description of the current writable
84 * space in the ringbuffer. The description is returned in a two
85 * element array of ringb_data_t. Two elements are needed
86 * because the space available for writing may be split across the end
88 * The first element will always contain a valid len field, which
89 * may be zero or greater. If the @a len field is non-zero, then data
90 * can be written in a contiguous fashion using the address given in
91 * the corresponding buf field.
92 * If the second element has a non-zero len field, then a second
93 * contiguous stretch of data can be written to the address given in
94 * the corresponding buf field.
95 * rb a pointer to the ringbuffer structure.
96 * vec a pointer to a 2 element array of ringb_data_t. */
98 extern void ringb_get_write_vector(const ringb_t *rb, ringb_data_t *vec);
101 * Read data from the ringbuffer.
102 * rb a pointer to the ringbuffer structure.
103 * dest a pointer to a buffer where data read from the
104 * ringbuffer will go.
105 * cnt the number of bytes to read.
107 * return the number of bytes read, which may range from 0 to cnt. */
109 extern size_t ringb_read(ringb_t *rb, char *dest, size_t cnt);
111 /* Read data from the ringbuffer. Opposed to ringb_read()
112 * this function does not move the read pointer. Thus it's
113 * a convenient way to inspect data in the ringbuffer in a
114 * continous fashion. The price is that the data is copied
115 * into a user provided buffer. For "raw" non-copy inspection
116 * of the data in the ringbuffer use ringb_get_read_vector().
117 * rb a pointer to the ringbuffer structure.
118 * dest a pointer to a buffer where data read from the
119 * ringbuffer will go.
120 * cnt the number of bytes to read.
121 * return the number of bytes read, which may range from 0 to cnt.
124 extern size_t ringb_peek(ringb_t *rb, char *dest, size_t cnt);
126 /* Advance the read pointer.
127 * After data have been read from the ringbuffer using the pointers
128 * returned by ringb_get_read_vector(), use this function to
129 * advance the buffer pointers, making that space available for future
132 * rb a pointer to the ringbuffer structure.
133 * cnt the number of bytes read. */
135 extern void ringb_read_advance(ringb_t *rb, size_t cnt);
137 /* Return the number of bytes available for reading.
138 * rb a pointer to the ringbuffer structure.
139 * return the number of bytes available to read. */
141 extern size_t ringb_read_space(const ringb_t *rb);
143 /* Reset the read and write pointers, making an empty buffer.
144 * This is not thread safe. */
146 extern void ringb_reset(ringb_t *rb);
148 /* Write data into the ringbuffer.
149 * rb a pointer to the ringbuffer structure.
150 * src a pointer to the data to be written to the ringbuffer.
151 * cnt the number of bytes to write.
152 * return the number of bytes write, which may range from 0 to cnt */
154 extern size_t ringb_write(ringb_t *rb, const char *src, size_t cnt);
156 /* Advance the write pointer.
157 * After data have been written the ringbuffer using the pointers
158 * returned by ringb_get_write_vector(), use this function
159 * to advance the buffer pointer, making the data available for future
161 * rb a pointer to the ringbuffer structure.
162 * cnt the number of bytes written. */
164 extern void ringb_write_advance(ringb_t *rb, size_t cnt);
166 /* Return the number of bytes available for writing.
167 * rb a pointer to the ringbuffer structure.
168 * return the amount of free space (in bytes) available for writing. */
170 extern size_t ringb_write_space(const ringb_t *rb);
172 /* Fill the ring buffer for nbytes at the beginning with zeros
173 * rb a pointer to the ring buffer structure
174 * nbytes the number of bytes to be written */
176 extern void ringb_clear(ringb_t *rb, size_t nbytes);
178 /* Reset the read and write pointers, making an empty buffer.
179 * This is not thread safe.
180 * Fill the ring buffer for nbytes at the beginning with zeros
181 * rb a pointer to the ring buffer structure
182 * nbytes the number of bytes to be written */
184 extern void ringb_restart(ringb_t *rb, size_t nbytes);