Object Management

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

Memory management is fundamental to using PrimoBurner effectively and efficiently. This topic is essential reading for all developers who use PrimoBurner. For managing memory PrimoBurner uses a reference-counting mechanism, and a policy of object ownership that is suggested by the names of interfaces and methods.

Ownership Policy

When trying to understand memory management in a PrimoBurner application, it is helpful to think not in terms of memory management per se, but instead in terms of object ownership. An object may have one or more owners; it records the number of owners it has using a reference count. If an object has no owners (if its reference count drops to zero), it is disposed of (freed). PrimoBurner defines the following rules for object ownership and disposal.

There are two distinct types of objects in PrimoBurner:

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

A PrimoBurner object is created through one of the following verbs: create, clone, copy and read.

1. Creating functions that begin with the word create in the C++ API (for example Library::createDataDisc and DeviceEnum::createDevice). The library creating functions have equivalent C exported functions beginning with pb_create (for example pb_create_data_disc).
2. Cloning functions like ErrorInfo::clone, AudioInput::clone and AudioOutput::clone.
3. Copy functions like DataDisc::copyImageLayout and VideoDVD::copyImageLayout.
4. Device read functions like Device::readCDText, Device::readDiscInfo, Device::readToc, etc. The information read by the device is returned through a new object instance and the ownership is transferred to the user code.

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 a PrimoBurner 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 PrimoBurner after the function returns then it is retained by the Library (for example when a CDTrack object is passed to CDTrackList::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 AudioOutput object is passed to AudioCD::readTrackFromCD 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 (clone/copy/read) 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 CDTrack object returned by CDTrackList::at even when the CDTrackList 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 PrimoBurner object and cannot be detached from it. Their lifetime depends only on the object that holds them. Objects without reference management do not inherit from primo::Reference.

Examples of such objects are:
AudioInputList returned by AudioCD::audioInputs,
UdfVolumeProps returned by DataDisc::udfVolumeProps,
BootProps returned by DataDisc::bootProps, etc.