#include <stddef.h>

Data Structures
union	AVRefStructOpaque
	RefStruct is an API for creating reference-counted objects with minimal overhead. More...

Macros
#define	AV_REFSTRUCT_FLAG_NO_ZEROING (1 << 0)
	If this flag is set in av_refstruct_alloc_ext_c(), the object will not be initially zeroed. More...

#define	AV_REFSTRUCT_POOL_FLAG_NO_ZEROING AV_REFSTRUCT_FLAG_NO_ZEROING
	If this flag is not set, every object in the pool will be zeroed before the init callback is called or before it is turned over to the user for the first time if no init callback has been provided. More...

#define	AV_REFSTRUCT_POOL_FLAG_RESET_ON_INIT_ERROR (1 << 16)
	If this flag is set and both init_cb and reset_cb callbacks are provided, then reset_cb will be called if init_cb fails. More...

#define	AV_REFSTRUCT_POOL_FLAG_FREE_ON_INIT_ERROR (1 << 17)
	If this flag is set and both init_cb and free_entry_cb callbacks are provided, then free_cb will be called if init_cb fails. More...

#define	AV_REFSTRUCT_POOL_FLAG_ZERO_EVERY_TIME (1 << 18)
	If this flag is set, the entries will be zeroed before being returned to the user (after the init or reset callbacks have been called (if provided)). More...

Functions
void *	av_refstruct_alloc_ext_c (size_t size, unsigned flags, AVRefStructOpaque opaque, void(free_cb)(AVRefStructOpaque opaque, void obj))
	Allocate a refcounted object of usable size `size` managed via the RefStruct API. More...

static void *	av_refstruct_alloc_ext (size_t size, unsigned flags, void opaque, void(free_cb)(AVRefStructOpaque opaque, void *obj))
	A wrapper around av_refstruct_alloc_ext_c() for the common case of a non-const qualified opaque. More...

static void *	av_refstruct_allocz (size_t size)
	Equivalent to av_refstruct_alloc_ext(size, 0, NULL, NULL) More...

void	av_refstruct_unref (void *objp)
	Decrement the reference count of the underlying object and automatically free the object if there are no more references to it. More...

void *	av_refstruct_ref (void *obj)
	Create a new reference to an object managed via this API, i.e. More...

const void *	av_refstruct_ref_c (const void *obj)
	Analog of av_refstruct_ref(), but for constant objects. More...

void	av_refstruct_replace (void dstp, const void src)
	Ensure `*dstp` refers to the same object as src. More...

int	av_refstruct_exclusive (const void *obj)
	Check whether the reference count of an object managed via this API is 1. More...

AVRefStructPool *	av_refstruct_pool_alloc (size_t size, unsigned flags)
	Equivalent to av_refstruct_pool_alloc(size, flags, NULL, NULL, NULL, NULL, NULL) More...

AVRefStructPool *	av_refstruct_pool_alloc_ext_c (size_t size, unsigned flags, AVRefStructOpaque opaque, int(init_cb)(AVRefStructOpaque opaque, void obj), void(reset_cb)(AVRefStructOpaque opaque, void obj), void(free_entry_cb)(AVRefStructOpaque opaque, void obj), void(*free_cb)(AVRefStructOpaque opaque))
	Allocate an AVRefStructPool, potentially using complex callbacks. More...

static AVRefStructPool *	av_refstruct_pool_alloc_ext (size_t size, unsigned flags, void opaque, int(init_cb)(AVRefStructOpaque opaque, void obj), void(reset_cb)(AVRefStructOpaque opaque, void obj), void(free_entry_cb)(AVRefStructOpaque opaque, void obj), void(free_cb)(AVRefStructOpaque opaque))
	A wrapper around av_refstruct_pool_alloc_ext_c() for the common case of a non-const qualified opaque. More...

void *	av_refstruct_pool_get (AVRefStructPool *pool)
	Get an object from the pool, reusing an old one from the pool when available. More...

static void	av_refstruct_pool_uninit (AVRefStructPool **poolp)
	Mark the pool as being available for freeing. More...

Macro Definition Documentation

◆ AV_REFSTRUCT_FLAG_NO_ZEROING

#define AV_REFSTRUCT_FLAG_NO_ZEROING (1 << 0)

If this flag is set in av_refstruct_alloc_ext_c(), the object will not be initially zeroed.

Definition at line 67 of file refstruct.h.

◆ AV_REFSTRUCT_POOL_FLAG_NO_ZEROING

#define AV_REFSTRUCT_POOL_FLAG_NO_ZEROING AV_REFSTRUCT_FLAG_NO_ZEROING

If this flag is not set, every object in the pool will be zeroed before the init callback is called or before it is turned over to the user for the first time if no init callback has been provided.

Definition at line 196 of file refstruct.h.

◆ AV_REFSTRUCT_POOL_FLAG_RESET_ON_INIT_ERROR

#define AV_REFSTRUCT_POOL_FLAG_RESET_ON_INIT_ERROR (1 << 16)

If this flag is set and both init_cb and reset_cb callbacks are provided, then reset_cb will be called if init_cb fails.

The object passed to reset_cb will be in the state left by init_cb.

Definition at line 202 of file refstruct.h.

◆ AV_REFSTRUCT_POOL_FLAG_FREE_ON_INIT_ERROR

#define AV_REFSTRUCT_POOL_FLAG_FREE_ON_INIT_ERROR (1 << 17)

If this flag is set and both init_cb and free_entry_cb callbacks are provided, then free_cb will be called if init_cb fails.

It will be called after reset_cb in case reset_cb and the av_refstruct_POOL_FLAG_RESET_ON_INIT_ERROR flag are also set.

The object passed to free_cb will be in the state left by the callbacks applied earlier (init_cb potentially followed by reset_cb).

Definition at line 213 of file refstruct.h.

◆ AV_REFSTRUCT_POOL_FLAG_ZERO_EVERY_TIME

#define AV_REFSTRUCT_POOL_FLAG_ZERO_EVERY_TIME (1 << 18)

If this flag is set, the entries will be zeroed before being returned to the user (after the init or reset callbacks have been called (if provided)).

Furthermore, to avoid zeroing twice it also makes the pool behave as if the av_refstruct_POOL_FLAG_NO_ZEROING flag had been provided.

Definition at line 221 of file refstruct.h.

Function Documentation

◆ av_refstruct_alloc_ext_c()

void* av_refstruct_alloc_ext_c	(	size_t	size,
		unsigned	flags,
		AVRefStructOpaque	opaque,
		void()(AVRefStructOpaque opaque, void obj)	free_cb
	)

Allocate a refcounted object of usable size size managed via the RefStruct API.

By default (in the absence of flags to the contrary), the returned object is initially zeroed.

Parameters

size	Desired usable size of the returned object.
flags	A bitwise combination of av_refstruct_FLAG_* flags.
opaque	A pointer that will be passed to the free_cb callback.
free_cb	A callback for freeing this object's content when its reference count reaches zero; it must not free the object itself.

Returns: A pointer to an object of the desired size or NULL on failure.

Definition at line 102 of file refstruct.c.

Referenced by av_refstruct_alloc_ext(), and cbs_alloc_content().

◆ av_refstruct_alloc_ext()

static void* av_refstruct_alloc_ext	(	size_t	size,
		unsigned	flags,
		void *	opaque,
		void()(AVRefStructOpaque opaque, void obj)	free_cb
	)

inlinestatic

A wrapper around av_refstruct_alloc_ext_c() for the common case of a non-const qualified opaque.

See also: av_refstruct_alloc_ext_c()

Definition at line 94 of file refstruct.h.

Referenced by alloc_progress(), aps_decode_alf(), av_refstruct_allocz(), av_refstruct_pool_alloc_ext_c(), ff_cbs_sei_alloc_message_payload(), ff_ffv1_planes_alloc(), ff_h264_decode_picture_parameter_set(), ff_hevc_decode_nal_pps(), ff_hevc_decode_nal_sps(), ff_hevc_decode_nal_vps(), ff_hwaccel_frame_priv_alloc(), ff_lcevc_alloc(), ff_v4l2_m2m_create_context(), nvdec_decoder_create(), pps_alloc(), qsv_create_mids(), refstruct_pool_get_ext(), rkmpp_init_decoder(), sps_alloc(), update_frame_pool(), vp3_decode_init(), and vulkan_decode_bootstrap().

◆ av_refstruct_allocz()

static void* av_refstruct_allocz ( size_t size )

inlinestatic

Equivalent to av_refstruct_alloc_ext(size, 0, NULL, NULL)

Definition at line 105 of file refstruct.h.

Referenced by alloc_frame(), aps_decode_scaling(), ff_dovi_rpu_generate(), ff_dovi_rpu_parse(), ff_h2645_sei_message_decode(), ff_h264_decode_seq_parameter_set(), ff_hwaccel_frame_priv_alloc(), ff_thread_get_ext_buffer(), parse_ext_blocks(), read_header(), sps(), vp8_alloc_frame(), and wv_dsd_reset().

◆ av_refstruct_unref()

void av_refstruct_unref ( void * objp )

Decrement the reference count of the underlying object and automatically free the object if there are no more references to it.

*objp == NULL is legal and a no-op.

Parameters

objp	Pointer to a pointer that is either NULL or points to an object managed via this API. `*objp` is set to NULL on return.

Definition at line 120 of file refstruct.c.

Referenced by alf_free(), alloc_and_insert_node(), alloc_progress(), aps_decode_alf(), aps_decode_scaling(), av1_decode_free(), av1_frame_unref(), av_container_fifo_drain(), av_container_fifo_free(), av_container_fifo_read(), av_container_fifo_write(), av_refstruct_pool_uninit(), av_refstruct_replace(), cbs_av1_close(), cbs_av1_write_obu(), cbs_clone_noncomplex_unit_content(), cbs_free_user_data_registered(), cbs_free_user_data_unregistered(), cbs_h2645_replace_ps(), cbs_h264_close(), cbs_h264_flush(), cbs_h265_close(), cbs_h265_flush(), cbs_h266_flush(), cbs_read_fragment_content(), cbs_sei_delete_message(), cbs_unit_uninit(), decode_pps(), decode_sps(), dts2pts_filter(), ff_cbs_make_unit_writable(), ff_cbs_sei_free_message_list(), ff_codec_close(), ff_decode_internal_uninit(), ff_dovi_ctx_flush(), ff_dovi_ctx_unref(), ff_dovi_rpu_generate(), ff_dovi_rpu_parse(), ff_ffv1_close(), ff_frame_thread_free(), ff_h2645_sei_message_decode(), ff_h2645_sei_reset(), ff_h264_decode_picture_parameter_set(), ff_h264_decode_seq_parameter_set(), ff_h264_ps_uninit(), ff_h264_unref_picture(), ff_hevc_decode_nal_pps(), ff_hevc_decode_nal_sps(), ff_hevc_decode_nal_vps(), ff_hevc_ps_uninit(), ff_hevc_unref_frame(), ff_lcevc_unref(), ff_mpv_encode_end(), ff_mpv_unref_picture(), ff_nvdec_decode_uninit(), ff_nvdec_start_frame_sep_ref(), ff_progress_frame_get_buffer(), ff_progress_frame_unref(), ff_qsv_enc_close(), ff_qsv_init_session_frames(), ff_thread_get_ext_buffer(), ff_thread_release_ext_buffer(), ff_v4l2_m2m_codec_end(), ff_v4l2_m2m_create_context(), ff_vk_decode_uninit(), ff_vvc_ctu_free_cus(), ff_vvc_frame_ps_free(), ff_vvc_ps_uninit(), ff_vvc_unref_frame(), free_node(), hevc_decode_free(), hevc_pps_free(), hevc_sps_free(), load_input_picture(), mpv_pic_reset(), nvdec_decoder_create(), nvdec_fdd_priv_free(), nvdec_unmap_mapped_frame(), pps_alloc(), pps_free(), qsv_decode_close_qsvcontext(), qsv_frame_alloc(), qsv_frame_free(), read_header(), remove_pps(), remove_sps(), remove_vps(), rkmpp_close_decoder(), rkmpp_release_frame(), select_input_picture(), set_bframe_chain_length(), set_sps(), slices_free(), sps_alloc(), sps_free(), update_frame_pool(), v4l2_free_buffer(), vaapi_encode_discard(), vaapi_encode_get_coded_data(), vaapi_encode_issue(), vaapi_encode_output(), vp3_decode_end(), vp8_alloc_frame(), vp8_release_frame(), vp9_frame_unref(), vulkan_decode_bootstrap(), wavpack_decode_block(), and wv_dsd_reset().

◆ av_refstruct_ref()

void* av_refstruct_ref ( void * obj )

Create a new reference to an object managed via this API, i.e.

increment the reference count of the underlying object and return obj.

Returns: a pointer equal to obj.

Definition at line 140 of file refstruct.c.

Referenced by attach_post_process_data(), cbs_av1_write_obu(), ff_cbs_insert_unit_content(), ff_cbs_sei_add_message(), ff_nvdec_start_frame(), ff_progress_frame_ref(), ff_thread_ref_frame(), get_current_frame(), hevc_ref_frame(), qsv_setup_mids(), rkmpp_retrieve_frame(), v4l2_buf_increase_ref(), and vaapi_encode_output().

◆ av_refstruct_ref_c()

const void* av_refstruct_ref_c ( const void * obj )

Analog of av_refstruct_ref(), but for constant objects.

See also: av_refstruct_ref()

Definition at line 149 of file refstruct.c.

Referenced by alloc_frame(), alloc_picture(), av_refstruct_replace(), ff_h264_decode_picture_parameter_set(), ff_hevc_decode_nal_pps(), ff_hevc_parse_sps(), hevc_ref_frame(), and set_sps().

◆ av_refstruct_replace()

void av_refstruct_replace	(	void *	dstp,
		const void *	src
	)

Ensure *dstp refers to the same object as src.

If *dstp is already equal to src, do nothing. Otherwise unreference *dstp and replace it with a new reference to src in case src != NULL (this involves incrementing the reference count of src's underlying object) or with NULL otherwise.

Parameters

dstp	Pointer to a pointer that is either NULL or points to an object managed via this API.
src	A pointer to an object managed via this API or NULL.

Definition at line 160 of file refstruct.c.

Referenced by aps_decode_alf(), aps_decode_scaling(), av1_frame_replace(), av1_receive_frame_internal(), cbs_av1_read_unit(), cbs_h2645_replace_ps(), cbs_h266_replace_ph(), decode_frame_ps(), decode_ph(), ff_decode_internal_sync(), ff_dovi_ctx_replace(), ff_h2645_sei_ctx_replace(), ff_h264_update_thread_context(), ff_mpv_replace_picture(), ff_mpv_workpic_from_pic(), ff_thread_replace_frame(), ff_thread_sync_ref(), ff_vk_update_thread_context(), ff_vvc_decode_aps(), ff_vvc_decode_sh(), h264_copy_picture_params(), h264_init_ps(), hevc_frame_start(), hevc_ref_frame(), parse_nal_units(), pps_alloc(), ref_frame(), slice_start(), sps_alloc(), update_context_from_thread(), and vp9_frame_replace().

◆ av_refstruct_exclusive()

int av_refstruct_exclusive ( const void * obj )

Check whether the reference count of an object managed via this API is 1.

Parameters

obj	A pointer to an object managed via this API.

Returns: 1 if the reference count of obj is 1; 0 otherwise.

Definition at line 174 of file refstruct.c.

Referenced by ff_cbs_make_unit_writable().

◆ av_refstruct_pool_alloc()

AVRefStructPool* av_refstruct_pool_alloc	(	size_t	size,
		unsigned	flags
	)

Equivalent to av_refstruct_pool_alloc(size, flags, NULL, NULL, NULL, NULL, NULL)

Definition at line 335 of file refstruct.c.

Referenced by dts2pts_init(), frame_context_init(), h264_init_context(), init_table_pools(), pic_arrays_init(), and vp9_frame_alloc().

◆ av_refstruct_pool_alloc_ext_c()

AVRefStructPool* av_refstruct_pool_alloc_ext_c	(	size_t	size,
		unsigned	flags,
		AVRefStructOpaque	opaque,
		int()(AVRefStructOpaque opaque, void obj)	init_cb,
		void()(AVRefStructOpaque opaque, void obj)	reset_cb,
		void()(AVRefStructOpaque opaque, void obj)	free_entry_cb,
		void(*)(AVRefStructOpaque opaque)	free_cb
	)

Allocate an AVRefStructPool, potentially using complex callbacks.

Parameters

size	size of the entries of the pool
flags	a bitwise combination of av_refstruct_POOL_FLAG_* flags
opaque	A pointer that will be passed to the callbacks below.
init	A callback that will be called directly after a new entry has been allocated. obj has already been zeroed unless the av_refstruct_POOL_FLAG_NO_ZEROING flag is in use.
reset	A callback that will be called after an entry has been returned to the pool and before it is reused.
free_entry	A callback that will be called when an entry is freed after the pool has been marked as to be uninitialized.
free	A callback that will be called when the pool itself is freed (after the last entry has been returned and freed).

Definition at line 340 of file refstruct.c.

Referenced by av_refstruct_pool_alloc_ext().

◆ av_refstruct_pool_alloc_ext()

static AVRefStructPool* av_refstruct_pool_alloc_ext	(	size_t	size,
		unsigned	flags,
		void *	opaque,
		int()(AVRefStructOpaque opaque, void obj)	init_cb,
		void()(AVRefStructOpaque opaque, void obj)	reset_cb,
		void()(AVRefStructOpaque opaque, void obj)	free_entry_cb,
		void(*)(AVRefStructOpaque opaque)	free_cb
	)

inlinestatic

A wrapper around av_refstruct_pool_alloc_ext_c() for the common case of a non-const qualified opaque.

See also: av_refstruct_pool_alloc_ext_c()

Definition at line 258 of file refstruct.h.

Referenced by av_container_fifo_alloc(), av_refstruct_pool_alloc(), ff_decode_preinit(), ff_mpv_alloc_pic_pool(), ff_nvdec_decode_init(), ff_vaapi_encode_init(), and wavpack_decode_init().

◆ av_refstruct_pool_get()

void* av_refstruct_pool_get ( AVRefStructPool * pool )

Get an object from the pool, reusing an old one from the pool when available.

Every call to this function must happen before av_refstruct_pool_uninit(). Otherwise undefined behaviour may occur.

Parameters

pool	the pool from which to get the object

Returns: a reference to the object on success, NULL on error.

Definition at line 297 of file refstruct.c.

Referenced by alloc_and_insert_node(), alloc_cu(), alloc_frame(), alloc_picture(), alloc_tu(), av_container_fifo_write(), ff_nvdec_start_frame(), ff_nvdec_start_frame_sep_ref(), ff_progress_frame_alloc(), load_input_picture(), vaapi_encode_issue(), vp9_frame_alloc(), and wavpack_decode_block().

◆ av_refstruct_pool_uninit()

static void av_refstruct_pool_uninit ( AVRefStructPool ** poolp )

inlinestatic

Mark the pool as being available for freeing.

It will actually be freed only once all the allocated buffers associated with the pool are released. Thus it is safe to call this function while some of the allocated buffers are still in use.

It is illegal to try to get a new entry after this function has been called.

Parameters

poolp pointer to a pointer to either NULL or a pool to be freed. *poolp will be set to NULL.

Definition at line 292 of file refstruct.h.

Referenced by av_container_fifo_free(), dts2pts_close(), ff_codec_close(), ff_h264_free_tables(), ff_mpv_decode_close(), ff_mpv_encode_end(), ff_nvdec_decode_uninit(), ff_vaapi_encode_close(), frame_context_free(), free_buffer_pools(), h264_decode_end(), init_table_pools(), pic_arrays_free(), pic_arrays_init(), vp9_decode_free(), vp9_frame_alloc(), and wavpack_decode_end().

Data Structures

Macros

Functions

Macro Definition Documentation

◆ AV_REFSTRUCT_FLAG_NO_ZEROING

◆ AV_REFSTRUCT_POOL_FLAG_NO_ZEROING

◆ AV_REFSTRUCT_POOL_FLAG_RESET_ON_INIT_ERROR

◆ AV_REFSTRUCT_POOL_FLAG_FREE_ON_INIT_ERROR

◆ AV_REFSTRUCT_POOL_FLAG_ZERO_EVERY_TIME

Function Documentation

◆ av_refstruct_alloc_ext_c()

◆ av_refstruct_alloc_ext()

◆ av_refstruct_allocz()

◆ av_refstruct_unref()

◆ av_refstruct_ref()

◆ av_refstruct_ref_c()

◆ av_refstruct_replace()

◆ av_refstruct_exclusive()

◆ av_refstruct_pool_alloc()

◆ av_refstruct_pool_alloc_ext_c()

◆ av_refstruct_pool_alloc_ext()

◆ av_refstruct_pool_get()

◆ av_refstruct_pool_uninit()