2
Copyright (C) 2000 Paul Davis
3
Copyright (C) 2003 Rohan Drape
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.
28
#include <sys/types.h>
30
/** @file ringbuffer.h
32
* A set of library functions to make lock-free ringbuffers available
33
* to JACK clients. The `capture_client.c' (in the example_clients
34
* directory) is a fully functioning user of this API.
36
* The key attribute of a ringbuffer is that it can be safely accessed
37
* by two threads simultaneously -- one reading from the buffer and
38
* the other writing to it -- without using any synchronization or
39
* mutual exclusion primitives. For this to work correctly, there can
40
* only be a single reader and a single writer thread. Their
41
* identities cannot be interchanged.
49
jack_ringbuffer_data_t ;
51
#define JRB_LOCKED 0x01
52
#define JRB_STOPPED 0x02
57
volatile size_t write_ptr;
58
volatile size_t read_ptr;
66
* Allocates a ringbuffer data structure of a specified size. The
67
* caller must arrange for a call to jack_ringbuffer_free() to release
68
* the memory associated with the ringbuffer.
70
* @param sz the ringbuffer size in bytes.
72
* @return a pointer to a new jack_ringbuffer_t, if successful; NULL
75
jack_ringbuffer_t *jack_ringbuffer_create(size_t sz);
78
* Frees the ringbuffer data structure allocated by an earlier call to
79
* jack_ringbuffer_create().
81
* @param rb a pointer to the ringbuffer structure.
83
void jack_ringbuffer_free(jack_ringbuffer_t *rb);
86
* Fill a data structure with a description of the current readable
87
* data held in the ringbuffer. This description is returned in a two
88
* element array of jack_ringbuffer_data_t. Two elements are needed
89
* because the data to be read may be split across the end of the
92
* The first element will always contain a valid @a len field, which
93
* may be zero or greater. If the @a len field is non-zero, then data
94
* can be read in a contiguous fashion using the address given in the
95
* corresponding @a buf field.
97
* If the second element has a non-zero @a len field, then a second
98
* contiguous stretch of data can be read from the address given in
99
* its corresponding @a buf field.
101
* @param rb a pointer to the ringbuffer structure.
102
* @param vec a pointer to a 2 element array of jack_ringbuffer_data_t.
105
void jack_ringbuffer_get_read_vector(const jack_ringbuffer_t *rb,
106
jack_ringbuffer_data_t *vec);
109
* Fill a data structure with a description of the current writable
110
* space in the ringbuffer. The description is returned in a two
111
* element array of jack_ringbuffer_data_t. Two elements are needed
112
* because the space available for writing may be split across the end
115
* The first element will always contain a valid @a len field, which
116
* may be zero or greater. If the @a len field is non-zero, then data
117
* can be written in a contiguous fashion using the address given in
118
* the corresponding @a buf field.
120
* If the second element has a non-zero @a len field, then a second
121
* contiguous stretch of data can be written to the address given in
122
* the corresponding @a buf field.
124
* @param rb a pointer to the ringbuffer structure.
125
* @param vec a pointer to a 2 element array of jack_ringbuffer_data_t.
127
void jack_ringbuffer_get_write_vector(const jack_ringbuffer_t *rb,
128
jack_ringbuffer_data_t *vec);
131
* Read data from the ringbuffer.
133
* @param rb a pointer to the ringbuffer structure.
134
* @param dest a pointer to a buffer where data read from the
135
* ringbuffer will go.
136
* @param cnt the number of bytes to read.
138
* @return the number of bytes read, which may range from 0 to cnt.
140
size_t jack_ringbuffer_read(jack_ringbuffer_t *rb, char *dest, size_t cnt);
143
* Read data from the ringbuffer. Opposed to jack_ringbuffer_read()
144
* this function does not move the read pointer. Thus it's
145
* a convenient way to inspect data in the ringbuffer in a
146
* continous fashion. The price is that the data is copied
147
* into a user provided buffer. For "raw" non-copy inspection
148
* of the data in the ringbuffer use jack_ringbuffer_get_read_vector().
150
* @param rb a pointer to the ringbuffer structure.
151
* @param dest a pointer to a buffer where data read from the
152
* ringbuffer will go.
153
* @param cnt the number of bytes to read.
155
* @return the number of bytes read, which may range from 0 to cnt.
157
size_t jack_ringbuffer_peek(jack_ringbuffer_t *rb, char *dest, size_t cnt);
160
* Advance the read pointer.
162
* After data have been read from the ringbuffer using the pointers
163
* returned by jack_ringbuffer_get_read_vector(), use this function to
164
* advance the buffer pointers, making that space available for future
167
* @param rb a pointer to the ringbuffer structure.
168
* @param cnt the number of bytes read.
170
void jack_ringbuffer_read_advance(jack_ringbuffer_t *rb, size_t cnt);
173
* Return the number of bytes available for reading.
175
* @param rb a pointer to the ringbuffer structure.
177
* @return the number of bytes available to read.
179
size_t jack_ringbuffer_read_space(const jack_ringbuffer_t *rb);
182
* Lock a ringbuffer data block into memory.
184
* Uses the mlock() system call. This is not a realtime operation.
186
* @param rb a pointer to the ringbuffer structure.
188
int jack_ringbuffer_mlock(jack_ringbuffer_t *rb);
190
void jack_ringbuffer_stop(jack_ringbuffer_t *rb);
191
void jack_ringbuffer_go(jack_ringbuffer_t *rb);
194
* Reset the read and write pointers, making an empty buffer.
196
* This is not thread safe.
198
* @param rb a pointer to the ringbuffer structure.
200
void jack_ringbuffer_reset(jack_ringbuffer_t *rb);
203
* Write data into the ringbuffer.
205
* @param rb a pointer to the ringbuffer structure.
206
* @param src a pointer to the data to be written to the ringbuffer.
207
* @param cnt the number of bytes to write.
209
* @return the number of bytes write, which may range from 0 to cnt
211
size_t jack_ringbuffer_write(jack_ringbuffer_t *rb, const char *src, size_t cnt);
214
* Advance the write pointer.
216
* After data have been written the ringbuffer using the pointers
217
* returned by jack_ringbuffer_get_write_vector(), use this function
218
* to advance the buffer pointer, making the data available for future
221
* @param rb a pointer to the ringbuffer structure.
222
* @param cnt the number of bytes written.
224
void jack_ringbuffer_write_advance(jack_ringbuffer_t *rb, size_t cnt);
227
* Return the number of bytes available for writing.
229
* @param rb a pointer to the ringbuffer structure.
231
* @return the amount of free space (in bytes) available for writing.
233
size_t jack_ringbuffer_write_space(const jack_ringbuffer_t *rb);
added
removed
include/bristol/ringbuffer.h
