Object Management

Common Rules for Object Management in AVBlocks (C++)

There are two distinct types of objects in AVBlocks:

1. Objects with reference management. They implement the primo::Reference interface. Most objects fall into this category.
2. Objects without reference management. They do not inherit from primo::Reference.

1. Objects with reference management.

These objects keep an internal reference count which is controlled via the primo::Reference interface. The count is increased via Reference::retain and decreased via Reference::release. By convention when an object with a reference count of 1 is released it is destroyed. As part of the destruction process the object releases all other objects that it has retained itself.

Creating Objects

An AVBlocks object is normally created with one of the AVBlocks creating functions. Those are all functions that begin with the word create in the C++ API (for example Library::createTranscoder and MediaSocket::createFromPreset). These C++ creating functions have equivalent C exported functions beginning with avb_create (for example avb_create_transcoder and avb_create_media_socket_from_preset). Another way to create new object instances is by using the clone method provided by some objects (like ErrorInfo::clone, StreamInfo::clone, AudioStreamInfo::clone and VideoStreamInfo::clone). An object that is created by one of the methods described above is reference counted. Its initial reference count is 1. The user code is responsible for managing such an object and it should be released when it is not needed anymore.

Passing Objects as Function Parameters

When an object is passed as a parameter to an AVBlocks function it may or may not be retained by the function. This depends on how the parameter is used in the Library and this is stated clearly in the documentation. The basic principle is that when the object will be used by AVBlocks after the function returns then it is retained by the Library (for example when a MediaPin object is passed to MediaPinList::add it is retained since it becomes part of the list). If the passed object is used only within the function then it is not retained (for example when a MediaSample object is passed to Transcoder::push it is not retained because it is used only within this method).

Returning Objects from Functions

A reference counted object can be returned either as a result of a creating operation (see Creating Objects above) or because the object already exists and it is being accessed. As already mentioned when a new object is created the user code is responsible to release it when it's not needed anymore. But when a reference counted object is simply accessed the user code should not release it. It should do so only if it has previously retained the object. This is an option that can be used when the returned object must be detached from the container (for example the client code may want to keep a MediaPin object even when the MediaSocket that holds it is destroyed).

2. Objects without reference management.

The objects that fall in this category cannot be created separately by the user code. They exist only in the context of another AVBlocks object and cannot be detached from it. Their lifetime depends only on the object that holds them.

Currently these are MediaPinList, MediaSocketList, MetaAttribute and MetaPictureList.