root/trunk/freebobstreaming/ringbuffer.h

Revision 150, 7.7 kB (checked in by pieterpalmers, 18 years ago)

- implement ALSA SEQ midi support

- fixed some small midi-related things

- changed the debug printing to the jackd messagebuffer based approach

- some small modification to the counters

- modified the packet handling on order to support lower buffer sizes and a lower number of buffers.
- it is possible to compile non-poll based support too

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