root/trunk/libffado/src/libutil/ringbuffer.h

Revision 742, 8.4 kB (checked in by ppalmers, 16 years ago)

- Remove some obsolete support files and dirs

- Clean up the license statements in the source files. Everything is

GPL version 3 now.

- Add license and copyright notices to scons scripts

- Clean up some other text files

Line 
1 /*
2  * Copyright (C) 2005-2007 by Pieter Palmers
3  *
4  * This file is part of FFADO
5  * FFADO = Free Firewire (pro-)audio drivers for linux
6  *
7  * FFADO is based upon FreeBoB
8  *
9  * This program is free software: you can redistribute it and/or modify
10  * it under the terms of the GNU General Public License as published by
11  * the Free Software Foundation, either version 3 of the License, or
12  * (at your option) any later version.
13  *
14  * This program is distributed in the hope that it will be useful,
15  * but WITHOUT ANY WARRANTY; without even the implied warranty of
16  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
17  * GNU General Public License for more details.
18  *
19  * You should have received a copy of the GNU General Public License
20  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
21  *
22  */
23
24 /*
25  * Copied from the jackd sources
26  * function names changed in order to avoid naming problems when using this in
27  * a jackd backend.
28  */
29
30 /* Original license:
31  * note that LGPL2.1 allows relicensing the code to GPLv3 or higher
32  *
33  *  Copyright (C) 2000 Paul Davis
34  *  Copyright (C) 2003 Rohan Drape
35  *
36  *  This program is free software; you can redistribute it and/or modify
37  *  it under the terms of the GNU Lesser General Public License as published by
38  *  the Free Software Foundation; either version 2.1 of the License, or
39  *  (at your option) any later version.
40  *
41  *  This program is distributed in the hope that it will be useful,
42  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
43  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
44  *  GNU Lesser General Public License for more details.
45  *
46  *  You should have received a copy of the GNU Lesser General Public License
47  *  along with this program; if not, write to the Free Software
48  *  Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
49  *
50  */
51
52 #ifndef _FFADO_RINGBUFFER_H
53 #define _FFADO_RINGBUFFER_H
54
55 #ifdef __cplusplus
56 extern "C" {
57 #endif
58
59 #include <sys/types.h>
60
61 /** @file ringbuffer.h
62  *
63  *
64  * The key attribute of a ringbuffer is that it can be safely accessed
65  * by two threads simultaneously -- one reading from the buffer and
66  * the other writing to it -- without using any synchronization or
67  * mutual exclusion primitives.  For this to work correctly, there can
68  * only be a single reader and a single writer thread.  Their
69  * identities cannot be interchanged.
70  */
71
72 typedef struct
73 {
74   char  *buf;
75   size_t len;
76 }
77 ffado_ringbuffer_data_t ;
78
79 typedef struct
80 {
81   char         *buf;
82   volatile size_t write_ptr;
83   volatile size_t read_ptr;
84   size_t      size;
85   size_t      size_mask;
86   int          mlocked;
87 }
88 ffado_ringbuffer_t ;
89
90 /**
91  * Allocates a ringbuffer data structure of a specified size. The
92  * caller must arrange for a call to ffado_ringbuffer_free() to release
93  * the memory associated with the ringbuffer.
94  *
95  * @param sz the ringbuffer size in bytes.
96  *
97  * @return a pointer to a new ffado_ringbuffer_t, if successful; NULL
98  * otherwise.
99  */
100 ffado_ringbuffer_t *ffado_ringbuffer_create(size_t sz);
101
102 /**
103  * Frees the ringbuffer data structure allocated by an earlier call to
104  * ffado_ringbuffer_create().
105  *
106  * @param rb a pointer to the ringbuffer structure.
107  */
108 void ffado_ringbuffer_free(ffado_ringbuffer_t *rb);
109
110 /**
111  * Fill a data structure with a description of the current readable
112  * data held in the ringbuffer.  This description is returned in a two
113  * element array of ffado_ringbuffer_data_t.  Two elements are needed
114  * because the data to be read may be split across the end of the
115  * ringbuffer.
116  *
117  * The first element will always contain a valid @a len field, which
118  * may be zero or greater.  If the @a len field is non-zero, then data
119  * can be read in a contiguous fashion using the address given in the
120  * corresponding @a buf field.
121  *
122  * If the second element has a non-zero @a len field, then a second
123  * contiguous stretch of data can be read from the address given in
124  * its corresponding @a buf field.
125  *
126  * @param rb a pointer to the ringbuffer structure.
127  * @param vec a pointer to a 2 element array of ffado_ringbuffer_data_t.
128  *
129  */
130 void ffado_ringbuffer_get_read_vector(const ffado_ringbuffer_t *rb,
131                      ffado_ringbuffer_data_t *vec);
132
133 /**
134  * Fill a data structure with a description of the current writable
135  * space in the ringbuffer.  The description is returned in a two
136  * element array of ffado_ringbuffer_data_t.  Two elements are needed
137  * because the space available for writing may be split across the end
138  * of the ringbuffer.
139  *
140  * The first element will always contain a valid @a len field, which
141  * may be zero or greater.  If the @a len field is non-zero, then data
142  * can be written in a contiguous fashion using the address given in
143  * the corresponding @a buf field.
144  *
145  * If the second element has a non-zero @a len field, then a second
146  * contiguous stretch of data can be written to the address given in
147  * the corresponding @a buf field.
148  *
149  * @param rb a pointer to the ringbuffer structure.
150  * @param vec a pointer to a 2 element array of ffado_ringbuffer_data_t.
151  */
152 void ffado_ringbuffer_get_write_vector(const ffado_ringbuffer_t *rb,
153                       ffado_ringbuffer_data_t *vec);
154
155 /**
156  * Read data from the ringbuffer.
157  *
158  * @param rb a pointer to the ringbuffer structure.
159  * @param dest a pointer to a buffer where data read from the
160  * ringbuffer will go.
161  * @param cnt the number of bytes to read.
162  *
163  * @return the number of bytes read, which may range from 0 to cnt.
164  */
165 size_t ffado_ringbuffer_read(ffado_ringbuffer_t *rb, char *dest, size_t cnt);
166
167 /**
168  * Read data from the ringbuffer. Opposed to ffado_ringbuffer_read()
169  * this function does not move the read pointer. Thus it's
170  * a convenient way to inspect data in the ringbuffer in a
171  * continous fashion. The price is that the data is copied
172  * into a user provided buffer. For "raw" non-copy inspection
173  * of the data in the ringbuffer use ffado_ringbuffer_get_read_vector().
174  *
175  * @param rb a pointer to the ringbuffer structure.
176  * @param dest a pointer to a buffer where data read from the
177  * ringbuffer will go.
178  * @param cnt the number of bytes to read.
179  *
180  * @return the number of bytes read, which may range from 0 to cnt.
181  */
182 size_t ffado_ringbuffer_peek(ffado_ringbuffer_t *rb, char *dest, size_t cnt);
183
184 /**
185  * Advance the read pointer.
186  *
187  * After data have been read from the ringbuffer using the pointers
188  * returned by ffado_ringbuffer_get_read_vector(), use this function to
189  * advance the buffer pointers, making that space available for future
190  * write operations.
191  *
192  * @param rb a pointer to the ringbuffer structure.
193  * @param cnt the number of bytes read.
194  */
195 void ffado_ringbuffer_read_advance(ffado_ringbuffer_t *rb, size_t cnt);
196
197 /**
198  * Return the number of bytes available for reading.
199  *
200  * @param rb a pointer to the ringbuffer structure.
201  *
202  * @return the number of bytes available to read.
203  */
204 size_t ffado_ringbuffer_read_space(const ffado_ringbuffer_t *rb);
205
206 /**
207  * Lock a ringbuffer data block into memory.
208  *
209  * Uses the mlock() system call.  This is not a realtime operation.
210  *
211  * @param rb a pointer to the ringbuffer structure.
212  */
213 int ffado_ringbuffer_mlock(ffado_ringbuffer_t *rb);
214
215 /**
216  * Reset the read and write pointers, making an empty buffer.
217  *
218  * This is not thread safe.
219  *
220  * @param rb a pointer to the ringbuffer structure.
221  */
222 void ffado_ringbuffer_reset(ffado_ringbuffer_t *rb);
223
224 /**
225  * Write data into the ringbuffer.
226  *
227  * @param rb a pointer to the ringbuffer structure.
228  * @param src a pointer to the data to be written to the ringbuffer.
229  * @param cnt the number of bytes to write.
230  *
231  * @return the number of bytes write, which may range from 0 to cnt
232  */
233 size_t ffado_ringbuffer_write(ffado_ringbuffer_t *rb, const char *src,
234                  size_t cnt);
235
236 /**
237  * Advance the write pointer.
238  *
239  * After data have been written the ringbuffer using the pointers
240  * returned by ffado_ringbuffer_get_write_vector(), use this function
241  * to advance the buffer pointer, making the data available for future
242  * read operations.
243  *
244  * @param rb a pointer to the ringbuffer structure.
245  * @param cnt the number of bytes written.
246  */
247 void ffado_ringbuffer_write_advance(ffado_ringbuffer_t *rb, size_t cnt);
248
249 /**
250  * Return the number of bytes available for writing.
251  *
252  * @param rb a pointer to the ringbuffer structure.
253  *
254  * @return the amount of free space (in bytes) available for writing.
255  */
256 size_t ffado_ringbuffer_write_space(const ffado_ringbuffer_t *rb);
257
258
259 #ifdef __cplusplus
260 }
261 #endif
262
263 #endif // FFADO_RINGBUFFER
Note: See TracBrowser for help on using the browser.