2
* Copyright (C) 2003 Paul Davis
4
* This program is free software; you can redistribute it and/or modify
5
* it under the terms of the GNU General Public License as published by
6
* the Free Software Foundation; either version 2 of the License, or
7
* (at your option) any later version.
9
* This program is distributed in the hope that it will be useful,
10
* but WITHOUT ANY WARRANTY; without even the implied warranty of
11
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12
* GNU General Public License for more details.
14
* $Id: ringbuffer.h,v 1.3 2003/11/19 15:28:17 theno23 Exp $
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.
19
$Id: ringbuffer.h,v 1.4 2004/01/15 06:26:08 joq Exp $
22
#ifndef JAMIN_RINGBUFFER_H
23
#define JAMIN_RINGBUFFER_H
25
/* use the built-in JACK ringbuffer implementation, if available */
26
#ifdef HAVE_JACK_RINGBUFFER
27
#include <jack/ringbuffer.h>
28
#else /* !HAVE_JACK_RINGBUFFER */
20
34
#include <sys/types.h>
36
/** @file ringbuffer.h
38
* A set of library functions to make lock-free ringbuffers available
39
* to JACK clients. The `capture_client.c' (in the example_clients
40
* directory) is a fully functioning user of this API.
42
* The key attribute of a ringbuffer is that it can be safely accessed
43
* by two threads simultaneously -- one reading from the buffer and
44
* the other writing to it -- without using any synchronization or
45
* mutual exclusion primitives. For this to work correctly, there can
46
* only be a single reader and a single writer thread. Their
47
* identities cannot be interchanged.
55
jack_ringbuffer_data_t ;
32
60
volatile size_t write_ptr;
33
61
volatile size_t read_ptr;
40
ringbuffer_t *ringbuffer_create(int sz);
41
void ringbuffer_free(ringbuffer_t *rb);
43
int ringbuffer_mlock(ringbuffer_t *rb);
44
void ringbuffer_reset(ringbuffer_t *rb);
46
void ringbuffer_write_advance(ringbuffer_t *rb, size_t cnt);
47
void ringbuffer_read_advance(ringbuffer_t *rb, size_t cnt);
49
size_t ringbuffer_write_space(ringbuffer_t *rb);
50
size_t ringbuffer_read_space(ringbuffer_t *rb);
52
size_t ringbuffer_read(ringbuffer_t *rb, char *dest, size_t cnt);
53
size_t ringbuffer_write(ringbuffer_t *rb, char *src, size_t cnt);
55
void ringbuffer_get_read_vector(ringbuffer_t *rb, ringbuffer_data_t *vec);
56
void ringbuffer_get_write_vector(ringbuffer_t *rb, ringbuffer_data_t *vec);
69
* Allocates a ringbuffer data structure of a specified size. The
70
* caller must arrange for a call to jack_ringbuffer_free() to release
71
* the memory associated with the ringbuffer.
73
* @param sz the ringbuffer size in bytes.
75
* @return a pointer to a new jack_ringbuffer_t, if successful; NULL
78
jack_ringbuffer_t *jack_ringbuffer_create(size_t sz);
81
* Frees the ringbuffer data structure allocated by an earlier call to
82
* jack_ringbuffer_create().
84
* @param rb a pointer to the ringbuffer structure.
86
void jack_ringbuffer_free(jack_ringbuffer_t *rb);
89
* Fill a data structure with a description of the current readable
90
* data held in the ringbuffer. This description is returned in a two
91
* element array of jack_ringbuffer_data_t. Two elements are needed
92
* because the data to be read may be split across the end of the
95
* The first element will always contain a valid @a len field, which
96
* may be zero or greater. If the @a len field is non-zero, then data
97
* can be read in a contiguous fashion using the address given in the
98
* corresponding @a buf field.
100
* If the second element has a non-zero @a len field, then a second
101
* contiguous stretch of data can be read from the address given in
102
* its corresponding @a buf field.
104
* @param rb a pointer to the ringbuffer structure.
105
* @param vec a pointer to a 2 element array of jack_ringbuffer_data_t.
108
void jack_ringbuffer_get_read_vector(const jack_ringbuffer_t *rb,
109
jack_ringbuffer_data_t *vec);
112
* Fill a data structure with a description of the current writable
113
* space in the ringbuffer. The description is returned in a two
114
* element array of jack_ringbuffer_data_t. Two elements are needed
115
* because the space available for writing may be split across the end
118
* The first element will always contain a valid @a len field, which
119
* may be zero or greater. If the @a len field is non-zero, then data
120
* can be written in a contiguous fashion using the address given in
121
* the corresponding @a buf field.
123
* If the second element has a non-zero @a len field, then a second
124
* contiguous stretch of data can be written to the address given in
125
* the corresponding @a buf field.
127
* @param rb a pointer to the ringbuffer structure.
128
* @param vec a pointer to a 2 element array of jack_ringbuffer_data_t.
130
void jack_ringbuffer_get_write_vector(const jack_ringbuffer_t *rb,
131
jack_ringbuffer_data_t *vec);
134
* Read data from the ringbuffer.
136
* @param rb a pointer to the ringbuffer structure.
137
* @param dest a pointer to a buffer where data read from the
138
* ringbuffer will go.
139
* @param cnt the number of bytes to read.
141
* @return the number of bytes read, which may range from 0 to cnt.
143
size_t jack_ringbuffer_read(jack_ringbuffer_t *rb, char *dest, size_t cnt);
146
* Advance the read pointer.
148
* After data have been read from the ringbuffer using the pointers
149
* returned by jack_ringbuffer_get_read_vector(), use this function to
150
* advance the buffer pointers, making that space available for future
153
* @param rb a pointer to the ringbuffer structure.
154
* @param cnt the number of bytes read.
156
void jack_ringbuffer_read_advance(jack_ringbuffer_t *rb, size_t cnt);
159
* Return the number of bytes available for reading.
161
* @param rb a pointer to the ringbuffer structure.
163
* @return the number of bytes available to read.
165
size_t jack_ringbuffer_read_space(const jack_ringbuffer_t *rb);
168
* Lock a ringbuffer data block into memory.
170
* Uses the mlock() system call. This is not a realtime operation.
172
* @param rb a pointer to the ringbuffer structure.
174
int jack_ringbuffer_mlock(jack_ringbuffer_t *rb);
177
* Reset the read and write pointers, making an empty buffer.
179
* This is not thread safe.
181
* @param rb a pointer to the ringbuffer structure.
183
void jack_ringbuffer_reset(jack_ringbuffer_t *rb);
186
* Write data into the ringbuffer.
188
* @param rb a pointer to the ringbuffer structure.
189
* @param src a pointer to the data to be written to the ringbuffer.
190
* @param cnt the number of bytes to write.
192
* @return the number of bytes write, which may range from 0 to cnt
194
size_t jack_ringbuffer_write(jack_ringbuffer_t *rb, const char *src,
198
* Advance the write pointer.
200
* After data have been written the ringbuffer using the pointers
201
* returned by jack_ringbuffer_get_write_vector(), use this function
202
* to advance the buffer pointer, making the data available for future
205
* @param rb a pointer to the ringbuffer structure.
206
* @param cnt the number of bytes written.
208
void jack_ringbuffer_write_advance(jack_ringbuffer_t *rb, size_t cnt);
211
* Return the number of bytes available for writing.
213
* @param rb a pointer to the ringbuffer structure.
215
* @return the amount of free space (in bytes) available for writing.
217
size_t jack_ringbuffer_write_space(const jack_ringbuffer_t *rb);
224
#endif /* HAVE_JACK_RINGBUFFER */
226
#endif /* JAMIN_RINGBUFFER_H */
added
removed
src/ringbuffer.h
