fifo.h File Reference

a very simple circular buffer FIFO implementation More...

#include <stddef.h>
#include <stdint.h>
#include "attributes.h"
#include "version.h"

Go to the source code of this file.

Data Structures
struct	AVFifoBuffer

Macros
#define	AV_FIFO_FLAG_AUTO_GROW   (1 << 0)
	Automatically resize the FIFO on writes, so that the data fits. More...

Typedefs
typedef struct AVFifo	AVFifo
typedef 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() functions. More...

Functions
AVFifo *	av_fifo_alloc2 (size_t elems, size_t elem_size, unsigned int flags)
	Allocate and initialize an AVFifo with a given element size. More...
size_t	av_fifo_elem_size (const AVFifo *f)
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. More...
size_t	av_fifo_can_read (const AVFifo *f)
size_t	av_fifo_can_write (const AVFifo *f)
int	av_fifo_grow2 (AVFifo *f, size_t inc)
	Enlarge an AVFifo. More...
int	av_fifo_write (AVFifo *f, const void *buf, size_t nb_elems)
	Write data into a FIFO. More...
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. More...
int	av_fifo_read (AVFifo *f, void *buf, size_t nb_elems)
	Read data from a FIFO. More...
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. More...
int	av_fifo_peek (AVFifo *f, void *buf, size_t nb_elems, size_t offset)
	Read data from a FIFO without modifying FIFO state. More...
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. More...
void	av_fifo_drain2 (AVFifo *f, size_t size)
	Discard the specified amount of data from an AVFifo. More...
void	av_fifo_reset2 (AVFifo *f)
void	av_fifo_freep2 (AVFifo **f)
	Free an AVFifo and reset pointer to NULL. More...
attribute_deprecated AVFifoBuffer *	av_fifo_alloc (unsigned int size)
	Initialize an AVFifoBuffer. More...
attribute_deprecated AVFifoBuffer *	av_fifo_alloc_array (size_t nmemb, size_t size)
	Initialize an AVFifoBuffer. More...
attribute_deprecated void	av_fifo_free (AVFifoBuffer *f)
	Free an AVFifoBuffer. More...
attribute_deprecated void	av_fifo_freep (AVFifoBuffer **f)
	Free an AVFifoBuffer and reset pointer to NULL. More...
attribute_deprecated void	av_fifo_reset (AVFifoBuffer *f)
	Reset the AVFifoBuffer to the state right after av_fifo_alloc, in particular it is emptied. More...
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 it. More...
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 into it. More...
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. More...
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. More...
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. More...
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. More...
attribute_deprecated int	av_fifo_realloc2 (AVFifoBuffer *f, unsigned int size)
	Resize an AVFifoBuffer. More...
attribute_deprecated int	av_fifo_grow (AVFifoBuffer *f, unsigned int additional_space)
	Enlarge an AVFifoBuffer. More...
attribute_deprecated void	av_fifo_drain (AVFifoBuffer *f, int size)
	Read and discard the specified amount of data from an AVFifoBuffer. More...
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. More...

Detailed Description

a very simple circular buffer FIFO implementation

Definition in file fifo.h.

Macro Definition Documentation

AV_FIFO_FLAG_AUTO_GROW

#define AV_FIFO_FLAG_AUTO_GROW   (1 << 0)

Automatically resize the FIFO on writes, so that the data fits.

This automatic resizing happens up to a limit that can be modified with av_fifo_auto_grow_limit().

Definition at line 58 of file fifo.h.

Typedef Documentation

AVFifo

typedef struct AVFifo AVFifo

Definition at line 33 of file fifo.h.

AVFifoCB

typedef 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() functions.

It may be invoked multiple times from a single av_fifo_*_cb() call and may process less data than the maximum size indicated by nb_elems.

Parameters

opaque	the opaque pointer provided to the av_fifo_*_cb() function
buf	the buffer for reading or writing the data, depending on which av_fifo_*_cb function is called
nb_elems	On entry contains the maximum number of elements that can be read from / written into buf. On success, the callback should update it to contain the number of elements actually written.

Returns

0 on success, a negative error code on failure (will be returned from the invoking av_fifo_*_cb() function)

Definition at line 51 of file fifo.h.

Function Documentation

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.

Parameters

elems	initial number of elements that can be stored in the FIFO
elem_size	Size in bytes of a single element. Further operations on the returned FIFO will implicitly use this element size.
flags	a combination of AV_FIFO_FLAG_*

Returns

newly-allocated AVFifo on success, a negative error code on failure

av_fifo_elem_size()

size_t av_fifo_elem_size

(

const AVFifo *

f

)

Returns

Element size for FIFO operations. This element size is set at FIFO allocation and remains constant during its lifetime

av_fifo_auto_grow_limit()

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.

Has no effect unless AV_FIFO_FLAG_AUTO_GROW is used.

av_fifo_can_read()

size_t av_fifo_can_read

(

const AVFifo *

f

)

Returns

number of elements available for reading from the given FIFO.

av_fifo_can_write()

size_t av_fifo_can_write

(

const AVFifo *

f

)

Returns

number of elements that can be written into the given FIFO.

av_fifo_grow2()

int av_fifo_grow2	(	AVFifo *	f,
		size_t	inc
	)

Enlarge an AVFifo.

On success, the FIFO will be large enough to hold exactly inc + av_fifo_can_read() + av_fifo_can_write() elements. In case of failure, the old FIFO is kept unchanged.

Parameters

f	AVFifo to resize
inc	number of elements to allocate for, in addition to the current allocated size

Returns

a non-negative number on success, a negative error code on failure

av_fifo_write()

int av_fifo_write	(	AVFifo *	f,
		const void *	buf,
		size_t	nb_elems
	)

Write data into a FIFO.

In case nb_elems > av_fifo_can_write(f), nothing is written and an error is returned.

Parameters

f	the FIFO buffer
buf	Data to be written. nb_elems * av_fifo_elem_size(f) bytes will be read from buf on success.
nb_elems	number of elements to write into FIFO

Returns

a non-negative number on success, a negative error code on failure

av_fifo_write_from_cb()

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.

Parameters

f	the FIFO buffer
read_cb	Callback supplying the data to the FIFO. May be called multiple times.
opaque	opaque user data to be provided to read_cb
nb_elems	Should point to the maximum number of elements that can be written. Will be updated to contain the number of elements actually written.

Returns

non-negative number on success, a negative error code on failure

av_fifo_read()

int av_fifo_read	(	AVFifo *	f,
		void *	buf,
		size_t	nb_elems
	)

Read data from a FIFO.

In case nb_elems > av_fifo_can_read(f), nothing is read and an error is returned.

Parameters

f	the FIFO buffer
buf	Buffer to store the data. nb_elems * av_fifo_elem_size(f) bytes will be written into buf on success.
nb_elems	number of elements to read from FIFO

Returns

a non-negative number on success, a negative error code on failure

av_fifo_read_to_cb()

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.

Parameters

f	the FIFO buffer
write_cb	Callback the data will be supplied to. May be called multiple times.
opaque	opaque user data to be provided to write_cb
nb_elems	Should point to the maximum number of elements that can be read. Will be updated to contain the total number of elements actually sent to the callback.

Returns

non-negative number on success, a negative error code on failure

av_fifo_peek()

int av_fifo_peek	(	AVFifo *	f,
		void *	buf,
		size_t	nb_elems,
		size_t	offset
	)

Read data from a FIFO without modifying FIFO state.

Returns an error if an attempt is made to peek to nonexistent elements (i.e. if offset + nb_elems is larger than av_fifo_can_read(f)).

Parameters

f	the FIFO buffer
buf	Buffer to store the data. nb_elems * av_fifo_elem_size(f) bytes will be written into buf.
nb_elems	number of elements to read from FIFO
offset	number of initial elements to skip.

Returns

a non-negative number on success, a negative error code on failure

av_fifo_peek_to_cb()

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.

Parameters

f	the FIFO buffer
write_cb	Callback the data will be supplied to. May be called multiple times.
opaque	opaque user data to be provided to write_cb
nb_elems	Should point to the maximum number of elements that can be read. Will be updated to contain the total number of elements actually sent to the callback.
offset	number of initial elements to skip; offset + *nb_elems must not be larger than av_fifo_can_read(f).

Returns

a non-negative number on success, a negative error code on failure

av_fifo_drain2()

void av_fifo_drain2	(	AVFifo *	f,
		size_t	size
	)

Discard the specified amount of data from an AVFifo.

Parameters

size	number of elements to discard, MUST NOT be larger than av_fifo_can_read(f)

av_fifo_reset2()

void av_fifo_reset2

(

AVFifo *

f

)

av_fifo_freep2()

void av_fifo_freep2

(

AVFifo **

f

)

Free an AVFifo and reset pointer to NULL.

Parameters

f	Pointer to an AVFifo to free. *f == NULL is allowed.

av_fifo_alloc()

attribute_deprecated AVFifoBuffer * av_fifo_alloc

(

unsigned int

size

)

Initialize an AVFifoBuffer.

Parameters

size

of FIFO

Returns

AVFifoBuffer or NULL in case of memory allocation failure

Deprecated:

use av_fifo_alloc2()

av_fifo_alloc_array()

attribute_deprecated AVFifoBuffer * av_fifo_alloc_array	(	size_t	nmemb,
		size_t	size
	)

Initialize an AVFifoBuffer.

Parameters

nmemb	number of elements
size	size of the single element

Returns

AVFifoBuffer or NULL in case of memory allocation failure

Deprecated:

use av_fifo_alloc2()

av_fifo_free()

attribute_deprecated void av_fifo_free

(

AVFifoBuffer *

f

)

Free an AVFifoBuffer.

Parameters

f	AVFifoBuffer to free

Deprecated:

use the AVFifo API with av_fifo_freep2()

av_fifo_freep()

attribute_deprecated void av_fifo_freep

(

AVFifoBuffer **

f

)

Free an AVFifoBuffer and reset pointer to NULL.

Parameters

f	AVFifoBuffer to free

Deprecated:

use the AVFifo API with av_fifo_freep2()

av_fifo_reset()

attribute_deprecated void av_fifo_reset

(

AVFifoBuffer *

f

)

Reset the AVFifoBuffer to the state right after av_fifo_alloc, in particular it is emptied.

Parameters

f	AVFifoBuffer to reset

Deprecated:

use av_fifo_reset2() with the new AVFifo-API

av_fifo_size()

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 it.

Parameters

f	AVFifoBuffer to read from

Returns

size

Deprecated:

use av_fifo_can_read() with the new AVFifo-API

av_fifo_space()

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 into it.

Parameters

f	AVFifoBuffer to write into

Returns

size

Deprecated:

use av_fifo_can_write() with the new AVFifo-API

av_fifo_generic_peek_at()

attribute_deprecated int av_fifo_generic_peek_at	(	AVFifoBuffer *	f,
		void *	dest,
		int	offset,
		int	buf_size,
		void(*)(void *, void *, int)	func
	)

Feed data at specific position from an AVFifoBuffer to a user-supplied callback.

Similar as av_fifo_gereric_read but without discarding data.

Parameters

f	AVFifoBuffer to read from
offset	offset from current read position
buf_size	number of bytes to read
func	generic read function
dest	data destination

Returns

a non-negative number on success, a negative error code on failure

Deprecated:

use the new AVFifo-API with av_fifo_peek() when func == NULL, av_fifo_peek_to_cb() otherwise

av_fifo_generic_peek()

attribute_deprecated int av_fifo_generic_peek	(	AVFifoBuffer *	f,
		void *	dest,
		int	buf_size,
		void(*)(void *, void *, int)	func
	)

Feed data from an AVFifoBuffer to a user-supplied callback.

Similar as av_fifo_gereric_read but without discarding data.

Parameters

f	AVFifoBuffer to read from
buf_size	number of bytes to read
func	generic read function
dest	data destination

Returns

a non-negative number on success, a negative error code on failure

Deprecated:

use the new AVFifo-API with av_fifo_peek() when func == NULL, av_fifo_peek_to_cb() otherwise

av_fifo_generic_read()

attribute_deprecated int av_fifo_generic_read	(	AVFifoBuffer *	f,
		void *	dest,
		int	buf_size,
		void(*)(void *, void *, int)	func
	)

Feed data from an AVFifoBuffer to a user-supplied callback.

Parameters

f	AVFifoBuffer to read from
buf_size	number of bytes to read
func	generic read function
dest	data destination

Returns

a non-negative number on success, a negative error code on failure

Deprecated:

use the new AVFifo-API with av_fifo_read() when func == NULL, av_fifo_read_to_cb() otherwise

av_fifo_generic_write()

attribute_deprecated int av_fifo_generic_write	(	AVFifoBuffer *	f,
		void *	src,
		int	size,
		int(*)(void *, void *, int)	func
	)

Feed data from a user-supplied callback to an AVFifoBuffer.

Parameters

f	AVFifoBuffer to write to
src	data source; non-const since it may be used as a modifiable context by the function defined in func
size	number of bytes to write
func	generic write function; the first parameter is src, the second is dest_buf, the third is dest_buf_size. func must return the number of bytes written to dest_buf, or <= 0 to indicate no more data available to write. If func is NULL, src is interpreted as a simple byte array for source data.

Returns

the number of bytes written to the FIFO or a negative error code on failure

Deprecated:

use the new AVFifo-API with av_fifo_write() when func == NULL, av_fifo_write_from_cb() otherwise

av_fifo_realloc2()

attribute_deprecated int av_fifo_realloc2	(	AVFifoBuffer *	f,
		unsigned int	size
	)

Resize an AVFifoBuffer.

In case of reallocation failure, the old FIFO is kept unchanged.

Parameters

f	AVFifoBuffer to resize
size	new AVFifoBuffer size in bytes

Returns

<0 for failure, >=0 otherwise

Deprecated:

use the new AVFifo-API with av_fifo_grow2() to increase FIFO size, decreasing FIFO size is not supported

av_fifo_grow()

attribute_deprecated int av_fifo_grow	(	AVFifoBuffer *	f,
		unsigned int	additional_space
	)

Enlarge an AVFifoBuffer.

In case of reallocation failure, the old FIFO is kept unchanged. The new fifo size may be larger than the requested size.

Parameters

f	AVFifoBuffer to resize
additional_space	the amount of space in bytes to allocate in addition to av_fifo_size()

Returns

<0 for failure, >=0 otherwise

Deprecated:

use the new AVFifo-API with av_fifo_grow2(); note that unlike this function it adds to the allocated size, rather than to the used size

av_fifo_drain()

attribute_deprecated void av_fifo_drain	(	AVFifoBuffer *	f,
		int	size
	)

Read and discard the specified amount of data from an AVFifoBuffer.

Parameters

f	AVFifoBuffer to read from
size	amount of data to read in bytes

Deprecated:

use the new AVFifo-API with av_fifo_drain2()

av_fifo_peek2()

static attribute_deprecated uint8_t * av_fifo_peek2 ( const AVFifoBuffer *  f, int  offs  )

inlinestatic

Return a pointer to the data stored in a FIFO buffer at a certain offset.

The FIFO buffer is not modified.

Parameters

f	AVFifoBuffer to peek at, f must be non-NULL
offs	an offset in bytes, its absolute value must be less than the used buffer size or the returned pointer will point outside to the buffer data. The used buffer size can be checked with av_fifo_size().

Deprecated:

use the new AVFifo-API with av_fifo_peek() or av_fifo_peek_to_cb()

Definition at line 414 of file fifo.h.