Reference Counting Objects Overview

Provides reference counting objects and specialist containers for using them.

Reference counting objects are largely used by server-side code to record the use of, and support access to, server-provided resources by multiple clients. The major motivation for the form of the API is to provide such functionality for the Kernel, which uses them in this way for system objects such as mutexes, threads, etc. The various container classes in the API provide the support for tracking the use of groups of such objects.

A reference counting object tracks the number of references to itself, and destroys itself when the final reference is removed. As well as a reference count, the interface provides special provision for such objects to have a name, and to have ownership relationships between each other.

The base class for reference counting objects is provided by CObject. A program sub-classes this to provide support for a type of a reference-counted resource.

A programs needs to manage the instances of each type of reference counting object that it provides. For this reason, all reference counting objects must be held in array-like objects called object containers. Each object container is assigned a unique ID on construction. Objects in the container can be found by index position, name, or find-handle (a combination of container ID and object index position).

The object container class is CObjectCon.

Object containers are themselves constructed through a class called an object container index, CObjectConIx. The object container index also has array-like features: it assigns an ID to each container created, and allows containers to be accessed through their IDs.

It can be useful to treat reference counting objects as members of groups other than their object containers. An object index is an array of references to reference-counted objects. Multiple instances of the same object, and objects from multiple object containers are allowed. As a way to identify their members, indexes can provide handle-numbers that combine the instance number of the reference counting object with the index of its position within the object index's array.

The object index class is CObjectIx.