Programming Reference: ODRefCntObject

# Programming Reference

## ODRefCntObject

Class Definition File | RefCtObj.idl
Class C++ Binding | RefCtObj.xh

Class Hierarchy

    SOMObject
       ODObject
          ODRefCntObject

Description

An object of the ODRefCntObject class implements reference counting, a mechanism that allows OpenDoc to manage memory used by objects.

In a typical OpenDoc session, various objects are shared by other objects, each of which has a reference to the shared object. A shared object must not be deleted if any object holds a reference to it. OpenDoc uses reference counting to manage memory for shared objects. Each reference-counted object keeps track of the number of existing references to it. An object's reference count indicates the number of objects that are using it. When an object's reference count drops to 0, no other object is using it; only then is it safe to delete the object, freeing the space it occupies in memory.

The ODRefCntObject class is the abstract superclass for all OpenDoc classes whose objects require reference counting. You should never instantiate ODRefCntObject itself, but you can instantiate a subclass by calling the appropriate factory method. If the factory method creates a new object, it sets the reference count for that object to 1; if the factory method returns a reference to an existing object, it increments that object's reference count by 1.

Memory management for each reference-counted class is the responsibility of its factory class. For example, the ODStorageSystem class is the factory class for the ODContainer class; that is, the storage system's factory method creates a container object. When the container object's reference count drops to 0, it informs the storage system, which deletes the container object.

Methods

The methods defined by the ODRefCntObject class include:

- Acquire
- GetRefCount
- InitRefCntObject
- Release

Overridden Methods | There are no methods overridden by the ODRefCntObject class.

### Acquire

This method increments an object's reference count by 1.

Signature

    void Acquire ()

Parameters

None.

Returns

None.

Remarks

Most methods that return a reference to a reference-counted object increment the object's reference count; however, if your part obtains a reference to a reference-counted object from a method that does not increment the object's reference count, you should call the object's Acquire method before you cache the reference in any structure. When the reference is replaced or removed from the data structure, you should call the object's Release method to decrement its reference count.

Override Policy

If you subclass the specific class, you must override this method if your part performs any specific actions when its reference count is incremented. Your override method must call its inherited method at the beginning of its implementation.

The inherited acquire method increments the reference count by 1. A part editor calls this method when it stores a reference to your part. When the reference is replaced or returned, the editor calls the Release method.

### GetRefCount

This method returns the current reference count of this object.

Signature

    ODULong GetRefCount ()

Parameters

None.

Returns

rv (ODULong) - returns

  The current reference count of this object.

### InitRefCntObject

This method initializes this object and sets its reference count to 1.

Signature

    void InitRefCntObject ()

Parameters

None.

Returns

None.

Remarks

This method is not called directly to initialize a reference-counted object, but is called by a subclass-specific initialization method. By convention, every subclass of ODRefCntObject should have a separate initialization method (for example, the InitMyRefCntObject method) that is called when an instance of that subclass is created, and that may have additional parameters beyond those of the InitRefCntObject method. The InitMyRefCntObject method should call the inherited InitRefCntObject method at the beginning of its implementation.

### Release

This method decrements an object's reference count by 1.

Signature

    void Release ()

Parameters

None.

Returns

None.

Remarks

When you no longer need an object reference that you obtained by calling a factory method (for example, the draft's CreatePart or AcquirePart method), you should call the object's Release method. In addition, you should balance every call to the object's Acquire method with a call to its Release method.

Exception Handling

kODErrZeroRefCount | The reference count cannot be decremented because the reference count is already 0.

Override Policy

If you subclass the specific class, you must override this method to release the object from memory if the object's count becomes 0 and reclaim the resource. Your override method must call its inherited method at the beginning of its implementation.

A part editor calls this method when it no longer needs a reference. The inherited release method decrements the reference count by 1. When the count becomes 0, the inherited method may delete the object or part.

For an extension object, the object's ReleaseExtension method is called when the count becomes 0 and the base object is not null.

[ Top | Previous | Next | Contents | Index | Documentation Homepage ]