Object Management

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

There are two distinct types of objects in DVDBuilder:

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 DVDBuilder object is normally created with one of the DVDBuilder creating functions. Those are all functions that begin with the word create in the C++ API (for example Library::createSubpictureEncoder). These C++ creating functions have equivalent C exported functions beginning with dvdb_create (for example dvdb_create_subpicture_encoder). Another way to create new object instances is by using the clone method provided by some objects (like ErrorInfo::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 DVDBuilder 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 DVDBuilder after the function returns then it is retained by the Library (for example when a VRDevice object is passed to VRDeviceList::add it is retained since it becomes part of the list).

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 VRDevice object even when the VRDeviceList 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 DVDBuilder object and cannot be detached from it. Their lifetime depends only on the object that holds them.

Currently these are Title.