IBM Visualization Data Explorer Programmer's Reference

4.2 Memory Management

The executive is responsible for managing Objects successfully returned as output by modules and for the memory allocated to those Objects. Any memory allocated or any Objects created that are not returned as output are the responsibility of the module. For instance, in an unsuccessful execution of a module, no Objects are returned. It is important that the programmer remember this difference when writing a module.

Allocating and Freeing Memory

Memory allocation results from either of the following:

• Calls to DXAllocate and DXAllocateLocal.

  In general, allocations resulting from these calls must be freed before returning.

• The creation of a new Object (e.g, by DXNewField or DXNewArray).

  On successful return, memory allocated for the use of these routines does not usually need to be freed: the Objects returned are managed by the executive, and the module is not responsible for their deletion. However, in case of error, no output Objects are returned, and the module is responsible for deleting all Objects created.

  When a Field is placed in a Group, the Field is deleted when the Group is deleted; and, on error, only the Group should be deleted. Similarly, an Array placed in a Field is deleted when the Field is deleted. For that reason it is often helpful to set the pointer of a Field or Array to NULL after placing it in a higher-level Object. The Field or Array can then be safely deleted on error, regardless of whether it has been placed in a higher-level Object.

Reference Counts

In Data Explorer, reference counts typically require no special action from the user. Thus modules seldom need to call DXReference for any reason, and they usually call DXDelete only to clean up Objects after an error. Note the following:

• All Objects are created with a reference count of zero (0).
• If you call DXDelete on an Object having a reference count of 0 or 1, the Object is invalidated and the space is freed. If the reference count is greater than 1, DXDelete simply decrements the count by 1 and returns.
• If an Object is incorporated in another Object by a call to DXSetComponentValue or DXSetMember, its reference count is incremented to 1.

  This means you can create Array Objects and use DXSetComponentValue to add them to a Field as a component, without having to call DXDelete: the Array will be deleted when the Field itself is deleted. (However, if an error occurs before you add the Array to the Field, you must call DXDelete.)

• Objects returned as output from your module should not be referenced.
• New Objects that are not part of another Object will have a reference count of 0. The executive increments the reference counts for outputs used by other modules and deletes the Objects when memory space is needed.

[Data Explorer Home Page | Contact Data Explorer | Same document on Data Explorer Home Page ]