Object Management

Objects with reference count 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 primo::avblocks::Library::createMediaSocket.

Another way to create new object instances is by using the clone method provided by some objects (like 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.

If the object will be used by AVBlocks after a 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 a 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 the push 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).

Objects without reference count 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 those objects are MediaPinList, MediaSocketList, MetaAttributeList and MetaPictureList.