FFmpeg
fifo.h
Go to the documentation of this file.
1 /*
2  * This file is part of FFmpeg.
3  *
4  * FFmpeg is free software; you can redistribute it and/or
5  * modify it under the terms of the GNU Lesser General Public
6  * License as published by the Free Software Foundation; either
7  * version 2.1 of the License, or (at your option) any later version.
8  *
9  * FFmpeg 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 GNU
12  * Lesser General Public License for more details.
13  *
14  * You should have received a copy of the GNU Lesser General Public
15  * License along with FFmpeg; if not, write to the Free Software
16  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
17  */
18 
19 /**
20  * @file
21  * @ingroup lavu_fifo
22  * A generic FIFO API
23  */
24 
25 #ifndef AVUTIL_FIFO_H
26 #define AVUTIL_FIFO_H
27 
28 #include <stddef.h>
29 #include <stdint.h>
30 
31 #include "attributes.h"
32 #include "version.h"
33 
34 /**
35  * @defgroup lavu_fifo AVFifo
36  * @ingroup lavu_data
37  *
38  * @{
39  * A generic FIFO API
40  */
41 
42 typedef struct AVFifo AVFifo;
43 
44 /**
45  * Callback for writing or reading from a FIFO, passed to (and invoked from) the
46  * av_fifo_*_cb() functions. It may be invoked multiple times from a single
47  * av_fifo_*_cb() call and may process less data than the maximum size indicated
48  * by nb_elems.
49  *
50  * @param opaque the opaque pointer provided to the av_fifo_*_cb() function
51  * @param buf the buffer for reading or writing the data, depending on which
52  * av_fifo_*_cb function is called
53  * @param nb_elems On entry contains the maximum number of elements that can be
54  * read from / written into buf. On success, the callback should
55  * update it to contain the number of elements actually written.
56  *
57  * @return 0 on success, a negative error code on failure (will be returned from
58  * the invoking av_fifo_*_cb() function)
59  */
60 typedef int AVFifoCB(void *opaque, void *buf, size_t *nb_elems);
61 
62 /**
63  * Automatically resize the FIFO on writes, so that the data fits. This
64  * automatic resizing happens up to a limit that can be modified with
65  * av_fifo_auto_grow_limit().
66  */
67 #define AV_FIFO_FLAG_AUTO_GROW (1 << 0)
68 
69 /**
70  * Allocate and initialize an AVFifo with a given element size.
71  *
72  * @param elems initial number of elements that can be stored in the FIFO
73  * @param elem_size Size in bytes of a single element. Further operations on
74  * the returned FIFO will implicitly use this element size.
75  * @param flags a combination of AV_FIFO_FLAG_*
76  *
77  * @return newly-allocated AVFifo on success, a negative error code on failure
78  */
79 AVFifo *av_fifo_alloc2(size_t elems, size_t elem_size,
80  unsigned int flags);
81 
82 /**
83  * @return Element size for FIFO operations. This element size is set at
84  * FIFO allocation and remains constant during its lifetime
85  */
86 size_t av_fifo_elem_size(const AVFifo *f);
87 
88 /**
89  * Set the maximum size (in elements) to which the FIFO can be resized
90  * automatically. Has no effect unless AV_FIFO_FLAG_AUTO_GROW is used.
91  */
92 void av_fifo_auto_grow_limit(AVFifo *f, size_t max_elems);
93 
94 /**
95  * @return number of elements available for reading from the given FIFO.
96  */
97 size_t av_fifo_can_read(const AVFifo *f);
98 
99 /**
100  * @return Number of elements that can be written into the given FIFO without
101  * growing it.
102  *
103  * In other words, this number of elements or less is guaranteed to fit
104  * into the FIFO. More data may be written when the
105  * AV_FIFO_FLAG_AUTO_GROW flag was specified at FIFO creation, but this
106  * may involve memory allocation, which can fail.
107  */
108 size_t av_fifo_can_write(const AVFifo *f);
109 
110 /**
111  * Enlarge an AVFifo.
112  *
113  * On success, the FIFO will be large enough to hold exactly
114  * inc + av_fifo_can_read() + av_fifo_can_write()
115  * elements. In case of failure, the old FIFO is kept unchanged.
116  *
117  * @param f AVFifo to resize
118  * @param inc number of elements to allocate for, in addition to the current
119  * allocated size
120  * @return a non-negative number on success, a negative error code on failure
121  */
122 int av_fifo_grow2(AVFifo *f, size_t inc);
123 
124 /**
125  * Write data into a FIFO.
126  *
127  * In case nb_elems > av_fifo_can_write(f) and the AV_FIFO_FLAG_AUTO_GROW flag
128  * was not specified at FIFO creation, nothing is written and an error
129  * is returned.
130  *
131  * Calling function is guaranteed to succeed if nb_elems <= av_fifo_can_write(f).
132  *
133  * @param f the FIFO buffer
134  * @param buf Data to be written. nb_elems * av_fifo_elem_size(f) bytes will be
135  * read from buf on success.
136  * @param nb_elems number of elements to write into FIFO
137  *
138  * @return a non-negative number on success, a negative error code on failure
139  */
140 int av_fifo_write(AVFifo *f, const void *buf, size_t nb_elems);
141 
142 /**
143  * Write data from a user-provided callback into a FIFO.
144  *
145  * @param f the FIFO buffer
146  * @param read_cb Callback supplying the data to the FIFO. May be called
147  * multiple times.
148  * @param opaque opaque user data to be provided to read_cb
149  * @param nb_elems Should point to the maximum number of elements that can be
150  * written. Will be updated to contain the number of elements
151  * actually written.
152  *
153  * @return non-negative number on success, a negative error code on failure
154  */
156  void *opaque, size_t *nb_elems);
157 
158 /**
159  * Read data from a FIFO.
160  *
161  * In case nb_elems > av_fifo_can_read(f), nothing is read and an error
162  * is returned.
163  *
164  * @param f the FIFO buffer
165  * @param buf Buffer to store the data. nb_elems * av_fifo_elem_size(f) bytes
166  * will be written into buf on success.
167  * @param nb_elems number of elements to read from FIFO
168  *
169  * @return a non-negative number on success, a negative error code on failure
170  */
171 int av_fifo_read(AVFifo *f, void *buf, size_t nb_elems);
172 
173 /**
174  * Feed data from a FIFO into a user-provided callback.
175  *
176  * @param f the FIFO buffer
177  * @param write_cb Callback the data will be supplied to. May be called
178  * multiple times.
179  * @param opaque opaque user data to be provided to write_cb
180  * @param nb_elems Should point to the maximum number of elements that can be
181  * read. Will be updated to contain the total number of elements
182  * actually sent to the callback.
183  *
184  * @return non-negative number on success, a negative error code on failure
185  */
187  void *opaque, size_t *nb_elems);
188 
189 /**
190  * Read data from a FIFO without modifying FIFO state.
191  *
192  * Returns an error if an attempt is made to peek to nonexistent elements
193  * (i.e. if offset + nb_elems is larger than av_fifo_can_read(f)).
194  *
195  * @param f the FIFO buffer
196  * @param buf Buffer to store the data. nb_elems * av_fifo_elem_size(f) bytes
197  * will be written into buf.
198  * @param nb_elems number of elements to read from FIFO
199  * @param offset number of initial elements to skip.
200  *
201  * @return a non-negative number on success, a negative error code on failure
202  */
203 int av_fifo_peek(AVFifo *f, void *buf, size_t nb_elems, size_t offset);
204 
205 /**
206  * Feed data from a FIFO into a user-provided callback.
207  *
208  * @param f the FIFO buffer
209  * @param write_cb Callback the data will be supplied to. May be called
210  * multiple times.
211  * @param opaque opaque user data to be provided to write_cb
212  * @param nb_elems Should point to the maximum number of elements that can be
213  * read. Will be updated to contain the total number of elements
214  * actually sent to the callback.
215  * @param offset number of initial elements to skip; offset + *nb_elems must not
216  * be larger than av_fifo_can_read(f).
217  *
218  * @return a non-negative number on success, a negative error code on failure
219  */
220 int av_fifo_peek_to_cb(AVFifo *f, AVFifoCB write_cb, void *opaque,
221  size_t *nb_elems, size_t offset);
222 
223 /**
224  * Discard the specified amount of data from an AVFifo.
225  * @param size number of elements to discard, MUST NOT be larger than
226  * av_fifo_can_read(f)
227  */
228 void av_fifo_drain2(AVFifo *f, size_t size);
229 
230 /*
231  * Empty the AVFifo.
232  * @param f AVFifo to reset
233  */
235 
236 /**
237  * Free an AVFifo and reset pointer to NULL.
238  * @param f Pointer to an AVFifo to free. *f == NULL is allowed.
239  */
241 
242 
243 #if FF_API_FIFO_OLD_API
244 typedef struct AVFifoBuffer {
245  uint8_t *buffer;
246  uint8_t *rptr, *wptr, *end;
247  uint32_t rndx, wndx;
248 } AVFifoBuffer;
249 
250 /**
251  * Initialize an AVFifoBuffer.
252  * @param size of FIFO
253  * @return AVFifoBuffer or NULL in case of memory allocation failure
254  * @deprecated use av_fifo_alloc2()
255  */
258 
259 /**
260  * Initialize an AVFifoBuffer.
261  * @param nmemb number of elements
262  * @param size size of the single element
263  * @return AVFifoBuffer or NULL in case of memory allocation failure
264  * @deprecated use av_fifo_alloc2()
265  */
267 AVFifoBuffer *av_fifo_alloc_array(size_t nmemb, size_t size);
268 
269 /**
270  * Free an AVFifoBuffer.
271  * @param f AVFifoBuffer to free
272  * @deprecated use the AVFifo API with av_fifo_freep2()
273  */
276 
277 /**
278  * Free an AVFifoBuffer and reset pointer to NULL.
279  * @param f AVFifoBuffer to free
280  * @deprecated use the AVFifo API with av_fifo_freep2()
281  */
284 
285 /**
286  * Reset the AVFifoBuffer to the state right after av_fifo_alloc, in particular it is emptied.
287  * @param f AVFifoBuffer to reset
288  * @deprecated use av_fifo_reset2() with the new AVFifo-API
289  */
292 
293 /**
294  * Return the amount of data in bytes in the AVFifoBuffer, that is the
295  * amount of data you can read from it.
296  * @param f AVFifoBuffer to read from
297  * @return size
298  * @deprecated use av_fifo_can_read() with the new AVFifo-API
299  */
302 
303 /**
304  * Return the amount of space in bytes in the AVFifoBuffer, that is the
305  * amount of data you can write into it.
306  * @param f AVFifoBuffer to write into
307  * @return size
308  * @deprecated use av_fifo_can_write() with the new AVFifo-API
309  */
312 
313 /**
314  * Feed data at specific position from an AVFifoBuffer to a user-supplied callback.
315  * Similar as av_fifo_gereric_read but without discarding data.
316  * @param f AVFifoBuffer to read from
317  * @param offset offset from current read position
318  * @param buf_size number of bytes to read
319  * @param func generic read function
320  * @param dest data destination
321  *
322  * @return a non-negative number on success, a negative error code on failure
323  *
324  * @deprecated use the new AVFifo-API with av_fifo_peek() when func == NULL,
325  * av_fifo_peek_to_cb() otherwise
326  */
328 int av_fifo_generic_peek_at(AVFifoBuffer *f, void *dest, int offset, int buf_size, void (*func)(void*, void*, int));
329 
330 /**
331  * Feed data from an AVFifoBuffer to a user-supplied callback.
332  * Similar as av_fifo_gereric_read but without discarding data.
333  * @param f AVFifoBuffer to read from
334  * @param buf_size number of bytes to read
335  * @param func generic read function
336  * @param dest data destination
337  *
338  * @return a non-negative number on success, a negative error code on failure
339  *
340  * @deprecated use the new AVFifo-API with av_fifo_peek() when func == NULL,
341  * av_fifo_peek_to_cb() otherwise
342  */
344 int av_fifo_generic_peek(AVFifoBuffer *f, void *dest, int buf_size, void (*func)(void*, void*, int));
345 
346 /**
347  * Feed data from an AVFifoBuffer to a user-supplied callback.
348  * @param f AVFifoBuffer to read from
349  * @param buf_size number of bytes to read
350  * @param func generic read function
351  * @param dest data destination
352  *
353  * @return a non-negative number on success, a negative error code on failure
354  *
355  * @deprecated use the new AVFifo-API with av_fifo_read() when func == NULL,
356  * av_fifo_read_to_cb() otherwise
357  */
359 int av_fifo_generic_read(AVFifoBuffer *f, void *dest, int buf_size, void (*func)(void*, void*, int));
360 
361 /**
362  * Feed data from a user-supplied callback to an AVFifoBuffer.
363  * @param f AVFifoBuffer to write to
364  * @param src data source; non-const since it may be used as a
365  * modifiable context by the function defined in func
366  * @param size number of bytes to write
367  * @param func generic write function; the first parameter is src,
368  * the second is dest_buf, the third is dest_buf_size.
369  * func must return the number of bytes written to dest_buf, or <= 0 to
370  * indicate no more data available to write.
371  * If func is NULL, src is interpreted as a simple byte array for source data.
372  * @return the number of bytes written to the FIFO or a negative error code on failure
373  *
374  * @deprecated use the new AVFifo-API with av_fifo_write() when func == NULL,
375  * av_fifo_write_from_cb() otherwise
376  */
378 int av_fifo_generic_write(AVFifoBuffer *f, void *src, int size, int (*func)(void*, void*, int));
379 
380 /**
381  * Resize an AVFifoBuffer.
382  * In case of reallocation failure, the old FIFO is kept unchanged.
383  *
384  * @param f AVFifoBuffer to resize
385  * @param size new AVFifoBuffer size in bytes
386  * @return <0 for failure, >=0 otherwise
387  *
388  * @deprecated use the new AVFifo-API with av_fifo_grow2() to increase FIFO size,
389  * decreasing FIFO size is not supported
390  */
392 int av_fifo_realloc2(AVFifoBuffer *f, unsigned int size);
393 
394 /**
395  * Enlarge an AVFifoBuffer.
396  * In case of reallocation failure, the old FIFO is kept unchanged.
397  * The new fifo size may be larger than the requested size.
398  *
399  * @param f AVFifoBuffer to resize
400  * @param additional_space the amount of space in bytes to allocate in addition to av_fifo_size()
401  * @return <0 for failure, >=0 otherwise
402  *
403  * @deprecated use the new AVFifo-API with av_fifo_grow2(); note that unlike
404  * this function it adds to the allocated size, rather than to the used size
405  */
407 int av_fifo_grow(AVFifoBuffer *f, unsigned int additional_space);
408 
409 /**
410  * Read and discard the specified amount of data from an AVFifoBuffer.
411  * @param f AVFifoBuffer to read from
412  * @param size amount of data to read in bytes
413  *
414  * @deprecated use the new AVFifo-API with av_fifo_drain2()
415  */
418 
419 #if FF_API_FIFO_PEEK2
420 /**
421  * Return a pointer to the data stored in a FIFO buffer at a certain offset.
422  * The FIFO buffer is not modified.
423  *
424  * @param f AVFifoBuffer to peek at, f must be non-NULL
425  * @param offs an offset in bytes, its absolute value must be less
426  * than the used buffer size or the returned pointer will
427  * point outside to the buffer data.
428  * The used buffer size can be checked with av_fifo_size().
429  * @deprecated use the new AVFifo-API with av_fifo_peek() or av_fifo_peek_to_cb()
430  */
432 static inline uint8_t *av_fifo_peek2(const AVFifoBuffer *f, int offs)
433 {
434  uint8_t *ptr = f->rptr + offs;
435  if (ptr >= f->end)
436  ptr = f->buffer + (ptr - f->end);
437  else if (ptr < f->buffer)
438  ptr = f->end - (f->buffer - ptr);
439  return ptr;
440 }
441 #endif
442 #endif
443 
444 /**
445  * @}
446  */
447 
448 #endif /* AVUTIL_FIFO_H */
Macro definitions for various function/variable attributes.
#define attribute_deprecated
Definition: attributes.h:100
unsigned size
allocated memory
Definition: bprint.h:99
attribute_deprecated int av_fifo_generic_peek_at(AVFifoBuffer *f, void *dest, int offset, int buf_size, void(*func)(void *, void *, int))
Feed data at specific position from an AVFifoBuffer to a user-supplied callback.
static attribute_deprecated uint8_t * av_fifo_peek2(const AVFifoBuffer *f, int offs)
Return a pointer to the data stored in a FIFO buffer at a certain offset.
Definition: fifo.h:432
attribute_deprecated void av_fifo_freep(AVFifoBuffer **f)
Free an AVFifoBuffer and reset pointer to NULL.
int av_fifo_peek_to_cb(AVFifo *f, AVFifoCB write_cb, void *opaque, size_t *nb_elems, size_t offset)
Feed data from a FIFO into a user-provided callback.
void av_fifo_freep2(AVFifo **f)
Free an AVFifo and reset pointer to NULL.
attribute_deprecated int av_fifo_space(const AVFifoBuffer *f)
Return the amount of space in bytes in the AVFifoBuffer, that is the amount of data you can write int...
attribute_deprecated int av_fifo_grow(AVFifoBuffer *f, unsigned int additional_space)
Enlarge an AVFifoBuffer.
void av_fifo_reset2(AVFifo *f)
int av_fifo_peek(AVFifo *f, void *buf, size_t nb_elems, size_t offset)
Read data from a FIFO without modifying FIFO state.
attribute_deprecated AVFifoBuffer * av_fifo_alloc_array(size_t nmemb, size_t size)
Initialize an AVFifoBuffer.
attribute_deprecated int av_fifo_generic_write(AVFifoBuffer *f, void *src, int size, int(*func)(void *, void *, int))
Feed data from a user-supplied callback to an AVFifoBuffer.
size_t av_fifo_can_write(const AVFifo *f)
attribute_deprecated int av_fifo_generic_peek(AVFifoBuffer *f, void *dest, int buf_size, void(*func)(void *, void *, int))
Feed data from an AVFifoBuffer to a user-supplied callback.
size_t av_fifo_can_read(const AVFifo *f)
attribute_deprecated void av_fifo_reset(AVFifoBuffer *f)
Reset the AVFifoBuffer to the state right after av_fifo_alloc, in particular it is emptied.
attribute_deprecated int av_fifo_size(const AVFifoBuffer *f)
Return the amount of data in bytes in the AVFifoBuffer, that is the amount of data you can read from ...
attribute_deprecated int av_fifo_generic_read(AVFifoBuffer *f, void *dest, int buf_size, void(*func)(void *, void *, int))
Feed data from an AVFifoBuffer to a user-supplied callback.
int av_fifo_read_to_cb(AVFifo *f, AVFifoCB write_cb, void *opaque, size_t *nb_elems)
Feed data from a FIFO into a user-provided callback.
AVFifo * av_fifo_alloc2(size_t elems, size_t elem_size, unsigned int flags)
Allocate and initialize an AVFifo with a given element size.
size_t av_fifo_elem_size(const AVFifo *f)
attribute_deprecated int av_fifo_realloc2(AVFifoBuffer *f, unsigned int size)
Resize an AVFifoBuffer.
int av_fifo_write_from_cb(AVFifo *f, AVFifoCB read_cb, void *opaque, size_t *nb_elems)
Write data from a user-provided callback into a FIFO.
int av_fifo_grow2(AVFifo *f, size_t inc)
Enlarge an AVFifo.
struct AVFifo AVFifo
Definition: fifo.h:42
int AVFifoCB(void *opaque, void *buf, size_t *nb_elems)
Callback for writing or reading from a FIFO, passed to (and invoked from) the av_fifo_*_cb() function...
Definition: fifo.h:60
attribute_deprecated AVFifoBuffer * av_fifo_alloc(unsigned int size)
Initialize an AVFifoBuffer.
int av_fifo_write(AVFifo *f, const void *buf, size_t nb_elems)
Write data into a FIFO.
void av_fifo_auto_grow_limit(AVFifo *f, size_t max_elems)
Set the maximum size (in elements) to which the FIFO can be resized automatically.
attribute_deprecated void av_fifo_drain(AVFifoBuffer *f, int size)
Read and discard the specified amount of data from an AVFifoBuffer.
void av_fifo_drain2(AVFifo *f, size_t size)
Discard the specified amount of data from an AVFifo.
attribute_deprecated void av_fifo_free(AVFifoBuffer *f)
Free an AVFifoBuffer.
int av_fifo_read(AVFifo *f, void *buf, size_t nb_elems)
Read data from a FIFO.
Libavutil version macros.
uint8_t * wptr
Definition: fifo.h:246
uint8_t * rptr
Definition: fifo.h:246
uint8_t * buffer
Definition: fifo.h:245
uint32_t rndx
Definition: fifo.h:247
uint32_t wndx
Definition: fifo.h:247
uint8_t * end
Definition: fifo.h:246