Home > User Guide > Bookkeeping in ACIS Assembly Modeling

Use Counting and Holding Objects in Assembly Modeling

ACIS Assembly Modeling has the following use-counted class types:

These use-counted class types fall into two categories: "model" objects and "handle" objects. Both model and handle objects are discussed in more detail in the following sections.

Topics include:

Use Counting Strategy Principles

The assembly modeling use counting strategy is intended to obviate the need for client code to explicitly manage use counts while at the same time permitting client code to use raw pointers (and lists of pointers) as the interface to assembly modeling methods. This is implemented using the following principles.

Principle 1: Every Use-counted Type Is Owned by a Corresponding "Manager" Object

A manager object is an object that maintains a list of use-counted objects and is responsible for managing "cleanup" of those objects. The purpose of the manager object is to ensure that there is always a pointer to a use-counted object available to ACIS (so that the object can be cleaned up), even when client code no longer has any pointers to the object.

Note:  asm_model objects are managed by a global asm_model_mgr object.

Note:  Handle objects are managed by an asm_model object:

Principle 2: Use-counted Objects Are Only Referred to by Their Pointers

For example, client code is not allowed to instantiate an entity_handle object on the stack.

Principle 3: The Use Count of an Object Is Incremented by "Holding" a Pointer to It in a Special Holder Object

The following objects are held by these holder objects:

In addition, each type object can be held by its corresponding list object, for example asm_model objects can be held by asm_model_lists. Refer to the section List Objects in Assembly Modeling.

Principle 4: The Use Count of an Object Is Automatically Decremented When a Holding Object Releases Its Pointer

The use count of an object is automatically decremented when a holding object releases its pointer (or is destructed).

Principle 5: List Objects Can Hold Objects Contained within the List

In addition to the holding objects, list objects can be set to hold the objects they contain. Refer to the section List Objects in Assembly Modeling for details.

Principle 6: A Use-counted Object Is Not Necessarily Destroyed When Its Use Count Becomes Zero

Destruction of the object is deferred until you explicitly call a "cleanup" routine (discussed below) on the object or its manager. The cleanup routine checks for objects which have zero use count and deletes them.

Principle 7: A Use-counted Object Can Be "Released" from Its Manager

In a released state, the use-counted object is destroyed immediately when its use count reaches zero. Handle objects are released when their managing model object is destroyed. Model objects are released either when the model manager is destroyed or when the assembly model tree is force-cleaned using asmi_model_cleanup_tree(). In general, an object that has been released should not be used by client code; the released state indicates that the object is slated for destruction as soon as there are no held pointers to it which might be mistakenly dereferenced.

Rules for Working with Pointers to Assembly Modeling Objects

The principles listed above lead to a simple set of rules for ACIS Assembly Modeling application developers to follow when working with pointers to assembly modeling objects.

Rule 1: Any Pointer Which Is Being Saved by the Application for Later Use Should Be Held by the Application

Any pointer which is being saved by the application for later use (for example, as a data member of an object with lifetime outside the scope of the routine where it is used) should be held, either by a holder object or by a list with holding behavior enabled. Any object that is not being held is subject to deletion by a cleanup() call.

Rule 2: Call cleanup() to Recover Memory Associated with Unused Handles

Application developers should make a cleanup() call when they wish to recover memory associated with unused handles. Application developers should strongly consider calling cleanup() immediately before saving assemblies to disk, as this will reduce the number of unused handles being saved. Application developers should also strongly consider calling cleanup() on models that have been restored from disk, but only after holding any handles (and the models) which the application will need.

Rule 3: Do Not Call cleanup() During Virtual or Callback Functions That Might Be Called by ACIS

Application developers should not make a cleanup() call during virtual or callback functions that might be called by ACIS. This prevents unexpected cleanup while ACIS routines are executing.

Note:  A holder object increments the use count of the object it is holding even when it is a data member of a backed-up copy of an entity on the history stream. In other words, an object's use count can be non-zero even if the only objects holding it have been lost. This behavior is necessary due to the fact that a lost entity can be resurrected by rolling history. Only ACIS can safely delete the object being pointed to when all copies of its holders, including those on the history stream, have been deleted from memory.

Cleanup Routines

The interface routines to cleanup model and handle objects are contained in the header file asm_cleanup_api.hxx. The routines are organized to permit customization of the cleanup request. The two axes of customization are which model objects should be examined and what type of objects associated with a model object that is being examined should be cleaned up.

For which model objects should be examined, the choices are:

For what type of objects associated with a model object that is being examined should be cleaned up, the choices are:

Using asmi_model_cleanup_tree

The routine asmi_model_cleanup_tree() is a special cleanup routine, intended if you have your own assembly modeling systems and are only using ACIS Assembly Modeling in order to read and write ASAT files. (Refer to the section Converting ACIS Assembly Models into Customer Assemblies for details.) After you have finished with the asm_model hierarchy, you should call asmi_model_cleanup_tree() with a force_clear flag of TRUE in order to release the models in the hierarchy from the global model manager.

Note: This routine should only be called on “top-level” models; no model in the input list should have a parent that is not in the input list or a sub-model of a model in the input list. This is to avoid the existence of parent models with model references to models in a released state.

Related topics:

Handles in Assembly Modeling
List Objects in Assembly Modeling

[Top]

© 1989-2007 Spatial Corp., a Dassault Systèmes company. All rights reserved.