FFmpeg  4.2.2
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  * a very simple circular buffer FIFO implementation
22  */
23 
24 #ifndef AVUTIL_FIFO_H
25 #define AVUTIL_FIFO_H
26 
27 #include <stdint.h>
28 #include "avutil.h"
29 #include "attributes.h"
30 typedef struct AVFifo AVFifo;
31 typedef struct AVFifoBuffer {
32  uint8_t *buffer;
33  uint8_t *rptr, *wptr, *end;
34  uint32_t rndx, wndx;
35 } AVFifoBuffer;
36 
37 /**
38  * Initialize an AVFifoBuffer.
39  * @param size of FIFO
40  * @return AVFifoBuffer or NULL in case of memory allocation failure
41  */
42 AVFifoBuffer *av_fifo_alloc(unsigned int size);
43 
44 typedef int AVFifoCB(void *opaque, void *buf, size_t *nb_elems);
45 /**
46  * Initialize an AVFifoBuffer.
47  * @param nmemb number of elements
48  * @param size size of the single element
49  * @return AVFifoBuffer or NULL in case of memory allocation failure
50  */
51 AVFifoBuffer *av_fifo_alloc_array(size_t nmemb, size_t size);
52 
53 /**
54  * Free an AVFifoBuffer.
55  * @param f AVFifoBuffer to free
56  */
57 void av_fifo_free(AVFifoBuffer *f);
58 
59 /**
60  * Free an AVFifoBuffer and reset pointer to NULL.
61  * @param f AVFifoBuffer to free
62  */
63 void av_fifo_freep(AVFifoBuffer **f);
64 
65 /**
66  * Reset the AVFifoBuffer to the state right after av_fifo_alloc, in particular it is emptied.
67  * @param f AVFifoBuffer to reset
68  */
70 
71 /**
72  * Return the amount of data in bytes in the AVFifoBuffer, that is the
73  * amount of data you can read from it.
74  * @param f AVFifoBuffer to read from
75  * @return size
76  */
77 int av_fifo_size(const AVFifoBuffer *f);
78 
79 /**
80  * Return the amount of space in bytes in the AVFifoBuffer, that is the
81  * amount of data you can write into it.
82  * @param f AVFifoBuffer to write into
83  * @return size
84  */
85 int av_fifo_space(const AVFifoBuffer *f);
86 
87 /**
88  * Feed data at specific position from an AVFifoBuffer to a user-supplied callback.
89  * Similar as av_fifo_gereric_read but without discarding data.
90  * @param f AVFifoBuffer to read from
91  * @param offset offset from current read position
92  * @param buf_size number of bytes to read
93  * @param func generic read function
94  * @param dest data destination
95  */
96 int av_fifo_generic_peek_at(AVFifoBuffer *f, void *dest, int offset, int buf_size, void (*func)(void*, void*, int));
97 
98 /**
99  * Feed data from an AVFifoBuffer to a user-supplied callback.
100  * Similar as av_fifo_gereric_read but without discarding data.
101  * @param f AVFifoBuffer to read from
102  * @param buf_size number of bytes to read
103  * @param func generic read function
104  * @param dest data destination
105  */
106 int av_fifo_generic_peek(AVFifoBuffer *f, void *dest, int buf_size, void (*func)(void*, void*, int));
107 
108 /**
109  * Feed data from an AVFifoBuffer to a user-supplied callback.
110  * @param f AVFifoBuffer to read from
111  * @param buf_size number of bytes to read
112  * @param func generic read function
113  * @param dest data destination
114  */
115 int av_fifo_generic_read(AVFifoBuffer *f, void *dest, int buf_size, void (*func)(void*, void*, int));
116 
117 /**
118  * Feed data from a user-supplied callback to an AVFifoBuffer.
119  * @param f AVFifoBuffer to write to
120  * @param src data source; non-const since it may be used as a
121  * modifiable context by the function defined in func
122  * @param size number of bytes to write
123  * @param func generic write function; the first parameter is src,
124  * the second is dest_buf, the third is dest_buf_size.
125  * func must return the number of bytes written to dest_buf, or <= 0 to
126  * indicate no more data available to write.
127  * If func is NULL, src is interpreted as a simple byte array for source data.
128  * @return the number of bytes written to the FIFO
129  */
130 int av_fifo_generic_write(AVFifoBuffer *f, void *src, int size, int (*func)(void*, void*, int));
131 
132 /**
133  * Resize an AVFifoBuffer.
134  * In case of reallocation failure, the old FIFO is kept unchanged.
135  *
136  * @param f AVFifoBuffer to resize
137  * @param size new AVFifoBuffer size in bytes
138  * @return <0 for failure, >=0 otherwise
139  */
140 int av_fifo_realloc2(AVFifoBuffer *f, unsigned int size);
141 
142 /**
143  * Enlarge an AVFifoBuffer.
144  * In case of reallocation failure, the old FIFO is kept unchanged.
145  * The new fifo size may be larger than the requested size.
146  *
147  * @param f AVFifoBuffer to resize
148  * @param additional_space the amount of space in bytes to allocate in addition to av_fifo_size()
149  * @return <0 for failure, >=0 otherwise
150  */
151 int av_fifo_grow(AVFifoBuffer *f, unsigned int additional_space);
152 
153 /**
154  * Read and discard the specified amount of data from an AVFifoBuffer.
155  * @param f AVFifoBuffer to read from
156  * @param size amount of data to read in bytes
157  */
158 void av_fifo_drain(AVFifoBuffer *f, int size);
159 
160 /**
161  * Return a pointer to the data stored in a FIFO buffer at a certain offset.
162  * The FIFO buffer is not modified.
163  *
164  * @param f AVFifoBuffer to peek at, f must be non-NULL
165  * @param offs an offset in bytes, its absolute value must be less
166  * than the used buffer size or the returned pointer will
167  * point outside to the buffer data.
168  * The used buffer size can be checked with av_fifo_size().
169  */
170 static inline uint8_t *av_fifo_peek2(const AVFifoBuffer *f, int offs)
171 {
172  uint8_t *ptr = f->rptr + offs;
173  if (ptr >= f->end)
174  ptr = f->buffer + (ptr - f->end);
175  else if (ptr < f->buffer)
176  ptr = f->end - (f->buffer - ptr);
177  return ptr;
178 }
179 
180 
181 /**
182  * Discard the specified amount of data from an AVFifo.
183  * @param size number of elements to discard, MUST NOT be larger than
184  * av_fifo_can_read(f)
185  */
186 void av_fifo_drain2(AVFifo *f, size_t size);
187 /**
188  * Read data from a FIFO.
189  *
190  * In case nb_elems > av_fifo_can_read(f), nothing is read and an error
191  * is returned.
192  *
193  * @param f the FIFO buffer
194  * @param buf Buffer to store the data. nb_elems * av_fifo_elem_size(f) bytes
195  * will be written into buf on success.
196  * @param nb_elems number of elements to read from FIFO
197  *
198  * @return a non-negative number on success, a negative error code on failure
199  */
200 int av_fifo_read(AVFifo *f, void *buf, size_t nb_elems);
201 /**
202  * Enlarge an AVFifo.
203  *
204  * On success, the FIFO will be large enough to hold exactly
205  * inc + av_fifo_can_read() + av_fifo_can_write()
206  * elements. In case of failure, the old FIFO is kept unchanged.
207  *
208  * @param f AVFifo to resize
209  * @param inc number of elements to allocate for, in addition to the current
210  * allocated size
211  * @return a non-negative number on success, a negative error code on failure
212  */
213 int av_fifo_grow2(AVFifo *f, size_t inc);
214 /**
215  * Free an AVFifo and reset pointer to NULL.
216  * @param f Pointer to an AVFifo to free. *f == NULL is allowed.
217  */
218 
219 /**
220  * @return number of elements available for reading from the given FIFO.
221  */
222 size_t av_fifo_can_read(const AVFifo *f);
223 
224 /**
225  * @return Number of elements that can be written into the given FIFO without
226  * growing it.
227  *
228  * In other words, this number of elements or less is guaranteed to fit
229  * into the FIFO. More data may be written when the
230  * AV_FIFO_FLAG_AUTO_GROW flag was specified at FIFO creation, but this
231  * may involve memory allocation, which can fail.
232  */
233 size_t av_fifo_can_write(const AVFifo *f);
234 
235 void av_fifo_freep2(AVFifo **f);
236 #define AV_FIFO_FLAG_AUTO_GROW (1 << 0)
237 /**
238  * Write data into a FIFO.
239  *
240  * In case nb_elems > av_fifo_can_write(f) and the AV_FIFO_FLAG_AUTO_GROW flag
241  * was not specified at FIFO creation, nothing is written and an error
242  * is returned.
243  *
244  * Calling function is guaranteed to succeed if nb_elems <= av_fifo_can_write(f).
245  *
246  * @param f the FIFO buffer
247  * @param buf Data to be written. nb_elems * av_fifo_elem_size(f) bytes will be
248  * read from buf on success.
249  * @param nb_elems number of elements to write into FIFO
250  *
251  * @return a non-negative number on success, a negative error code on failure
252  */
253 int av_fifo_write(AVFifo *f, const void *buf, size_t nb_elems);
254 
255 /**
256  * Allocate and initialize an AVFifo with a given element size.
257  *
258  * @param elems initial number of elements that can be stored in the FIFO
259  * @param elem_size Size in bytes of a single element. Further operations on
260  * the returned FIFO will implicitly use this element size.
261  * @param flags a combination of AV_FIFO_FLAG_*
262  *
263  * @return newly-allocated AVFifo on success, a negative error code on failure
264  */
265 AVFifo *av_fifo_alloc2(size_t elems, size_t elem_size,
266  unsigned int flags);
267 
268 #endif /* AVUTIL_FIFO_H */
av_fifo_generic_peek_at
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.
av_fifo_realloc2
int av_fifo_realloc2(AVFifoBuffer *f, unsigned int size)
Resize an AVFifoBuffer.
AVFifoBuffer::wptr
uint8_t * wptr
Definition: fifo.h:33
av_fifo_freep2
void av_fifo_freep2(AVFifo **f)
av_fifo_alloc2
AVFifo * av_fifo_alloc2(size_t elems, size_t elem_size, unsigned int flags)
Allocate and initialize an AVFifo with a given element size.
av_fifo_generic_read
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.
AVFifoBuffer
Definition: fifo.h:31
av_fifo_reset
void av_fifo_reset(AVFifoBuffer *f)
Reset the AVFifoBuffer to the state right after av_fifo_alloc, in particular it is emptied.
AVFifo
struct AVFifo AVFifo
Definition: fifo.h:30
av_fifo_size
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 ...
av_fifo_generic_peek
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.
av_fifo_write
int av_fifo_write(AVFifo *f, const void *buf, size_t nb_elems)
Write data into a FIFO.
av_fifo_drain
void av_fifo_drain(AVFifoBuffer *f, int size)
Read and discard the specified amount of data from an AVFifoBuffer.
av_fifo_can_write
size_t av_fifo_can_write(const AVFifo *f)
av_fifo_grow
int av_fifo_grow(AVFifoBuffer *f, unsigned int additional_space)
Enlarge an AVFifoBuffer.
av_fifo_read
int av_fifo_read(AVFifo *f, void *buf, size_t nb_elems)
Read data from a FIFO.
AVFifoCB
int AVFifoCB(void *opaque, void *buf, size_t *nb_elems)
Definition: fifo.h:44
AVFifoBuffer::end
uint8_t * end
Definition: fifo.h:33
av_fifo_alloc_array
AVFifoBuffer * av_fifo_alloc_array(size_t nmemb, size_t size)
Initialize an AVFifoBuffer.
av_fifo_generic_write
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.
av_fifo_peek2
static 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:170
attributes.h
AVFifoBuffer::buffer
uint8_t * buffer
Definition: fifo.h:32
AVFifoBuffer::wndx
uint32_t wndx
Definition: fifo.h:34
av_fifo_freep
void av_fifo_freep(AVFifoBuffer **f)
Free an AVFifoBuffer and reset pointer to NULL.
av_fifo_can_read
size_t av_fifo_can_read(const AVFifo *f)
Free an AVFifo and reset pointer to NULL.
av_fifo_grow2
int av_fifo_grow2(AVFifo *f, size_t inc)
Enlarge an AVFifo.
av_fifo_free
void av_fifo_free(AVFifoBuffer *f)
Free an AVFifoBuffer.
avutil.h
av_fifo_drain2
void av_fifo_drain2(AVFifo *f, size_t size)
Discard the specified amount of data from an AVFifo.
AVFifoBuffer::rptr
uint8_t * rptr
Definition: fifo.h:33
av_fifo_alloc
AVFifoBuffer * av_fifo_alloc(unsigned int size)
Initialize an AVFifoBuffer.
AVFifoBuffer::rndx
uint32_t rndx
Definition: fifo.h:34
av_fifo_space
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...