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.
29
#include <sys/types.h>
31
/** @file ringbuffer.h
33
* A set of library functions to make lock-free ringbuffers available
34
* to JACK clients. The `capture_client.c' (in the example_clients
35
* directory) is a fully functioning user of this API.
37
* The key attribute of a ringbuffer is that it can be safely accessed
38
* by two threads simultaneously -- one reading from the buffer and
39
* the other writing to it -- without using any synchronization or
40
* mutual exclusion primitives. For this to work correctly, there can
41
* only be a single reader and a single writer thread. Their
42
* identities cannot be interchanged.
49
jack_ringbuffer_data_t ;
53
volatile size_t write_ptr;
54
volatile size_t read_ptr;
62
* Allocates a ringbuffer data structure of a specified size. The
63
* caller must arrange for a call to jack_ringbuffer_free() to release
64
* the memory associated with the ringbuffer.
66
* @param sz the ringbuffer size in bytes.
68
* @return a pointer to a new jack_ringbuffer_t, if successful; NULL
71
jack_ringbuffer_t *jack_ringbuffer_create(size_t sz);
74
* Frees the ringbuffer data structure allocated by an earlier call to
75
* jack_ringbuffer_create().
77
* @param rb a pointer to the ringbuffer structure.
79
void jack_ringbuffer_free(jack_ringbuffer_t *rb);
82
* Fill a data structure with a description of the current readable
83
* data held in the ringbuffer. This description is returned in a two
84
* element array of jack_ringbuffer_data_t. Two elements are needed
85
* because the data to be read may be split across the end of the
88
* The first element will always contain a valid @a len field, which
89
* may be zero or greater. If the @a len field is non-zero, then data
90
* can be read in a contiguous fashion using the address given in the
91
* corresponding @a buf field.
93
* If the second element has a non-zero @a len field, then a second
94
* contiguous stretch of data can be read from the address given in
95
* its corresponding @a buf field.
97
* @param rb a pointer to the ringbuffer structure.
98
* @param vec a pointer to a 2 element array of jack_ringbuffer_data_t.
101
void jack_ringbuffer_get_read_vector(const jack_ringbuffer_t *rb,
102
jack_ringbuffer_data_t *vec);
105
* Fill a data structure with a description of the current writable
106
* space in the ringbuffer. The description is returned in a two
107
* element array of jack_ringbuffer_data_t. Two elements are needed
108
* because the space available for writing may be split across the end
111
* The first element will always contain a valid @a len field, which
112
* may be zero or greater. If the @a len field is non-zero, then data
113
* can be written in a contiguous fashion using the address given in
114
* the corresponding @a buf field.
116
* If the second element has a non-zero @a len field, then a second
117
* contiguous stretch of data can be written to the address given in
118
* the corresponding @a buf field.
120
* @param rb a pointer to the ringbuffer structure.
121
* @param vec a pointer to a 2 element array of jack_ringbuffer_data_t.
123
void jack_ringbuffer_get_write_vector(const jack_ringbuffer_t *rb,
124
jack_ringbuffer_data_t *vec);
127
* Read data from the ringbuffer.
129
* @param rb a pointer to the ringbuffer structure.
130
* @param dest a pointer to a buffer where data read from the
131
* ringbuffer will go.
132
* @param cnt the number of bytes to read.
134
* @return the number of bytes read, which may range from 0 to cnt.
136
size_t jack_ringbuffer_read(jack_ringbuffer_t *rb, char *dest, size_t cnt);
139
* Read data from the ringbuffer. Opposed to jack_ringbuffer_read()
140
* this function does not move the read pointer. Thus it's
141
* a convenient way to inspect data in the ringbuffer in a
142
* continous fashion. The price is that the data is copied
143
* into a user provided buffer. For "raw" non-copy inspection
144
* of the data in the ringbuffer use jack_ringbuffer_get_read_vector().
146
* @param rb a pointer to the ringbuffer structure.
147
* @param dest a pointer to a buffer where data read from the
148
* ringbuffer will go.
149
* @param cnt the number of bytes to read.
151
* @return the number of bytes read, which may range from 0 to cnt.
153
size_t jack_ringbuffer_peek(jack_ringbuffer_t *rb, char *dest, size_t cnt);
156
* Advance the read pointer.
158
* After data have been read from the ringbuffer using the pointers
159
* returned by jack_ringbuffer_get_read_vector(), use this function to
160
* advance the buffer pointers, making that space available for future
163
* @param rb a pointer to the ringbuffer structure.
164
* @param cnt the number of bytes read.
166
void jack_ringbuffer_read_advance(jack_ringbuffer_t *rb, size_t cnt);
169
* Return the number of bytes available for reading.
171
* @param rb a pointer to the ringbuffer structure.
173
* @return the number of bytes available to read.
175
size_t jack_ringbuffer_read_space(const jack_ringbuffer_t *rb);
178
* Lock a ringbuffer data block into memory.
180
* Uses the mlock() system call. This is not a realtime operation.
182
* @param rb a pointer to the ringbuffer structure.
184
int jack_ringbuffer_mlock(jack_ringbuffer_t *rb);
187
* Reset the read and write pointers, making an empty buffer.
189
* This is not thread safe.
191
* @param rb a pointer to the ringbuffer structure.
193
void jack_ringbuffer_reset(jack_ringbuffer_t *rb);
196
* Reset the internal "available" size, and read and write pointers, making an empty buffer.
198
* This is not thread safe.
200
* @param rb a pointer to the ringbuffer structure.
201
* @param sz the new size, that must be less than allocated size.
203
void jack_ringbuffer_reset_size (jack_ringbuffer_t * rb, size_t sz);
206
* Write data into the ringbuffer.
208
* @param rb a pointer to the ringbuffer structure.
209
* @param src a pointer to the data to be written to the ringbuffer.
210
* @param cnt the number of bytes to write.
212
* @return the number of bytes write, which may range from 0 to cnt
214
size_t jack_ringbuffer_write(jack_ringbuffer_t *rb, const char *src,
218
* Advance the write pointer.
220
* After data have been written the ringbuffer using the pointers
221
* returned by jack_ringbuffer_get_write_vector(), use this function
222
* to advance the buffer pointer, making the data available for future
225
* @param rb a pointer to the ringbuffer structure.
226
* @param cnt the number of bytes written.
228
void jack_ringbuffer_write_advance(jack_ringbuffer_t *rb, size_t cnt);
231
* Return the number of bytes available for writing.
233
* @param rb a pointer to the ringbuffer structure.
235
* @return the amount of free space (in bytes) available for writing.
237
size_t jack_ringbuffer_write_space(const jack_ringbuffer_t *rb);
added
removed
os/mac/include/jack/ringbuffer.h
