Home > User Guide > Bookkeeping in ACIS Assembly Modeling

Handles in Assembly Modeling

Handle objects are proxies in the assembly domain which allow assembly mode code to refer to objects for which a pointer to the object is not a "good" identifier in assembly mode. (Refer to the sections Assembly Modeling vs Part Modeling and Assembly Modeling Tutorial for a discussion of assembly mode.) Handle objects are always owned by an asm_model object, and are only exposed to client code as pointers. (Refer to the section Use Counting and Holding Objects in Assembly Modeling for a discussion of handle ownership.) The ACIS Assembly Modeling interface uses handle object pointers in the same way that ACIS Part Modeling uses ENTITY pointers; interface functions take handle pointers or handle lists as parameters, with the handle list classes supporting the same operations as ENTITY_LIST. (Refer to the section List Objects in Assembly Modeling for a discussion of handle lists.)

Topics include:

Handle Types

The types of handle objects in ACIS Assembly Modeling include:

Need for Handles

For each of these handle object types, using a pointer to the underlying object as an identifier would be unsafe. In each case, this is related to the requirement that asm_model objects can be bound to different history streams; that is, the contents of models can roll independently. (Refer to the section History and Roll in Assembly Modeling.) In essence, the underlying objects can become invalid due to history operations. In the case of entity handles, if the underlying ENTITY is lost or destructed, then any pointers to that ENTITY become invalid without any notification being given to the object holding the pointer. A pointer to the ENTITY’s entity_handle object, however, remains valid because the entity_handle does not participate in history. The entity handle can be queried for a pointer to its underlying ENTITY; if the ENTITY has been lost or destructed, then the query will return a NULL value. If a lost entity is revived by rolling its history stream, then querying its entity handle for its ENTITY's pointer value will again return a non-NULL value.

The impact of independent history streams on components and component entities is more subtle because they are not ENTITYs. Instead, they correspond to a sequence of model references (in the case of components) or a sequence of model references terminated by an entity (in the case of component entities). Because these model references live in different models, the validity of a particular component (or component entity) can be affected by deletions or roll operations in any of those models. This, in turn, means that an identifier is needed for each component or component entity which is unaffected by the state of its underlying entities.

Note:  Although this section discusses "component" and "component_entity" as abstract concepts class types representing these concepts are not a part of ACIS. All of the services that such class types would provide are instead provided by the corresponding handle types and the ASMI interface routines which act upon them. If such class types are introduced in a future version of ACIS, however, they will not be derived from ENTITY.

Entity Handle as a Fundamental Type

Note that, to a large extent, entity_handle is the fundamental data object in assembly modeling (in the same way that ENTITY is the fundamental data type in part modeling). The other two handle types can be thought of as referring to aggregations of entity handles:

Handle Data

Each of the three handle types has underlying data associated with it, which can be queried by client code:

In addition, all handles are owned/managed by an asm_model object, and can be queried for their owning model with a get_owning_model() method:

Component Entity Handle as the Assembly Modeling Analogue of ENTITY

In ACIS Part Modeling, the unique identifier for elements of the model is ENTITY*. In ACIS Assembly Modeling, ENTITY* is not the case. For example, the pointer to a FACE within a wheel part is not a unique identifier in a car assembly because the face appears four times within the assembly. The unique identifier in ACIS Assembly Modeling is component_entity_handle*; each of the four appearances of the wheel’s face corresponds to a unique component entity handle.

Handle Validity

Because handles are designed to manage interaction with objects which might be invalid (either temporarily or permanently), additional care must be taken by client code which uses handles. A handle object is invalid whenever either it or one of the handle objects it contains returns NULL when queried for its associated ENTITY pointer:

Client code must written to be robust against invalid handles; that is, a handle's validity should be explicitly checked before it is used. Generally speaking, invalid handles should simply be ignored when iterating through a list of handles in order to perform some operation(s) on each handle. Note that an invalid handle can become valid again if the operation which made the handle invalid is rolled away. Each of the handle types has an is_valid() method which will indicate if the handle being queried is currently valid.

Handle Holding

It is extremely important that any handle object which will be used by client code outside the scope of the routine (or after an explicit call to cleanup) where it is obtained be "held" (have its use-count incremented by placing it in a holding object or list). Refer to Use Counting and Holding Objects in Assembly Modeling for a discussion of handle ownership.

Related topics:

Use Counting and Holding Objects in Assembly Modeling
List Objects in Assembly Modeling

[Top]

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