** Warning: Cannot open xref database.
1 /*
2 Copyright (C) 2000 Paul Davis
3 Copyright (C) 2003 Rohan Drape
4
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.
9
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.
14
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.
18
19 $Id: ringbuffer.h,v 1.4 2003/12/21 02:40:46 joq Exp $
20 */
21
22 #ifndef _RINGBUFFER_H
23 #define _RINGBUFFER_H
24
25 #ifdef __cplusplus
26 extern "C" {
27 #endif
28
29 #include <sys/types.h>
30
31 /** @file ringbuffer.h
32 *
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.
36 *
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.
43 */
44
45 typedef struct
46 {
47 char *buf;
48 size_t len;
49 }
50 jack_ringbuffer_data_t ;
51
52 typedef struct
53 {
54 char *buf;
55 volatile size_t write_ptr;
56 volatile size_t read_ptr;
57 size_t size;
58 size_t size_mask;
59 int mlocked;
60 }
61 jack_ringbuffer_t ;
62
63 /**
64 * Allocates a ringbuffer data structure of a specified size. The
65 * caller must arrange for a call to jack_ringbuffer_free() to release
66 * the memory associated with the ringbuffer.
67 *
68 * @param sz the ringbuffer size in bytes.
69 *
70 * @return a pointer to a new jack_ringbuffer_t, if successful; NULL
71 * otherwise.
72 */
73 jack_ringbuffer_t *jack_ringbuffer_create(size_t sz);
74
75 /**
76 * Frees the ringbuffer data structure allocated by an earlier call to
77 * jack_ringbuffer_create().
78 *
79 * @param rb a pointer to the ringbuffer structure.
80 */
81 void jack_ringbuffer_free(jack_ringbuffer_t *rb);
82
83 /**
84 * Fill a data structure with a description of the current readable
85 * data held in the ringbuffer. This description is returned in a two
86 * element array of jack_ringbuffer_data_t. Two elements are needed
87 * because the data to be read may be split across the end of the
88 * ringbuffer.
89 *
90 * The first element will always contain a valid @a len field, which
91 * may be zero or greater. If the @a len field is non-zero, then data
92 * can be read in a contiguous fashion using the address given in the
93 * corresponding @a buf field.
94 *
95 * If the second element has a non-zero @a len field, then a second
96 * contiguous stretch of data can be read from the address given in
97 * its corresponding @a buf field.
98 *
99 * @param rb a pointer to the ringbuffer structure.
100 * @param vec a pointer to a 2 element array of jack_ringbuffer_data_t.
101 *
102 */
103 void jack_ringbuffer_get_read_vector(jack_ringbuffer_t *rb,
104 jack_ringbuffer_data_t *vec);
105
106 /**
107 * Fill a data structure with a description of the current writable
108 * space in the ringbuffer. The description is returned in a two
109 * element array of jack_ringbuffer_data_t. Two elements are needed
110 * because the space available for writing may be split across the end
111 * of the ringbuffer.
112 *
113 * The first element will always contain a valid @a len field, which
114 * may be zero or greater. If the @a len field is non-zero, then data
115 * can be written in a contiguous fashion using the address given in
116 * the corresponding @a buf field.
117 *
118 * If the second element has a non-zero @a len field, then a second
119 * contiguous stretch of data can be written to the address given in
120 * the corresponding @a buf field.
121 *
122 * @param rb a pointer to the ringbuffer structure.
123 * @param vec a pointer to a 2 element array of jack_ringbuffer_data_t.
124 */
125 void jack_ringbuffer_get_write_vector(jack_ringbuffer_t *rb,
126 jack_ringbuffer_data_t *vec);
127
128 /**
129 * Read data from the ringbuffer.
130 *
131 * @param rb a pointer to the ringbuffer structure.
132 * @param dest a pointer to a buffer where data read from the
133 * ringbuffer will go.
134 * @param cnt the number of bytes to read.
135 *
136 * @return the number of bytes read, which may range from 0 to cnt.
137 */
138 size_t jack_ringbuffer_read(jack_ringbuffer_t *rb, char *dest, size_t cnt);
139
140 /**
141 * Advance the read pointer.
142 *
143 * After data have been read from the ringbuffer using the pointers
144 * returned by jack_ringbuffer_get_read_vector(), use this function to
145 * advance the buffer pointers, making that space available for future
146 * write operations.
147 *
148 * @param rb a pointer to the ringbuffer structure.
149 * @param cnt the number of bytes read.
150 */
151 void jack_ringbuffer_read_advance(jack_ringbuffer_t *rb, size_t cnt);
152
153 /**
154 * Return the number of bytes available for reading.
155 *
156 * @param rb a pointer to the ringbuffer structure.
157 *
158 * @return the number of bytes available to read.
159 */
160 size_t jack_ringbuffer_read_space(jack_ringbuffer_t *rb);
161
162 /**
163 * Lock a ringbuffer data block into memory.
164 *
165 * Uses the mlock() system call. This is not a realtime operation.
166 *
167 * @param rb a pointer to the ringbuffer structure.
168 */
169 int jack_ringbuffer_mlock(jack_ringbuffer_t *rb);
170
171 /**
172 * Reset the read and write pointers, making an empty buffer.
173 *
174 * This is not thread safe.
175 *
176 * @param rb a pointer to the ringbuffer structure.
177 */
178 void jack_ringbuffer_reset(jack_ringbuffer_t *rb);
179
180 /**
181 * Write data into the ringbuffer.
182 *
183 * @param rb a pointer to the ringbuffer structure.
184 * @param src a pointer to the data to be written to the ringbuffer.
185 * @param cnt the number of bytes to write.
186 *
187 * @return the number of bytes write, which may range from 0 to cnt
188 */
189 size_t jack_ringbuffer_write(jack_ringbuffer_t *rb, char *src, size_t cnt);
190
191 /**
192 * Advance the write pointer.
193 *
194 * After data have been written the ringbuffer using the pointers
195 * returned by jack_ringbuffer_get_write_vector(), use this function
196 * to advance the buffer pointer, making the data available for future
197 * read operations.
198 *
199 * @param rb a pointer to the ringbuffer structure.
200 * @param cnt the number of bytes written.
201 */
202 void jack_ringbuffer_write_advance(jack_ringbuffer_t *rb, size_t cnt);
203
204 /**
205 * Return the number of bytes available for writing.
206 *
207 * @param rb a pointer to the ringbuffer structure.
208 *
209 * @return the amount of free space (in bytes) available for writing.
210 */
211 size_t jack_ringbuffer_write_space(jack_ringbuffer_t *rb);
212
213
214 #ifdef __cplusplus
215 }
216 #endif
217
218 #endif
219
This page was automatically generated by the
LXR engine.
Visit the LXR main site for more
information.