Next: , Previous: , Up: API Basics   [Contents][Index]


1.10.3 Object Handles

QSMM uses handles for referencing various objects visible to an application program. A handle is an opaque typed pointer to a QSMM internal structure. The application program cannot examine or change its content other than by calling API functions that take a handle of this type as an argument. The type of a handle corresponds to the type of an object referenced by the handle. Dereferencing handles does not make sense as they have incomplete types. Because a handle is a pointer, it can have the NULL value.

The table below lists handle types used in QSMM. For each handle type, the table indicates a corresponding object type and a reference to a section in this manual with a detailed description of that handle type.

Handle typeObject typeReference to a section in this manual
qsmm_tmultinode modelCreating a Multinode Model.
qsmm_actor_tactorCreating an Actor.
qsmm_actpair_tactor pairCreating the Model Instance.
qsmm_instr_tassembler instructionBasic Datatypes.
qsmm_iter_tmap iteratorPart of C implementation of functionality of STL map and multimap templates. See Creating Maps and Iterators.
qsmm_map_tmapPart of C implementation of functionality of STL map and multimap templates. See Creating Maps and Iterators.
qsmm_msg_tmessageCreating Messages.
qsmm_msglist_tmessage listCreating a Message List.
qsmm_prg_tassembler programBasic Datatypes.
qsmm_rng_trandom number generatorCreating a Random Number Generator.
qsmm_side_tinteraction sidePart of Side API. See Registering Interaction Sides.
qsmm_storage_tstatistics storageTypes of Storage.
qsmm_vec_tvectorOrdinary and Sparse Vectors.

Note: It is generally acceptable to call API functions for different handles in different threads of a multithreaded program concurrently on condition that those handles do not reference interrelated objects (e.g. when an object is a component of another object). Calling API functions for the same handle (in different threads of a multithreaded program concurrently) is not thread-safe except for the Side API intended for communication between threads.

The following enumeration specifies possible handle types.

Enumeration: qsmm_handle_e

This enumeration lists supported types of object handles. The enumeration contains the following elements.

QSMM_HANDLE_INVALID

A special value designating an invalid, unknown, or NULL object handle type.

QSMM_HANDLE_MODEL

A multinode model handle. It has the type qsmm_t.

QSMM_HANDLE_ACTOR

An actor handle. It has the type qsmm_actor_t.

QSMM_HANDLE_ACTPAIR

An actor pair handle. It has the type qsmm_actpair_t.

QSMM_HANDLE_INSTR

An assembler instruction handle. It has the type qsmm_instr_t.

QSMM_HANDLE_ITER

A key-value map iterator handle. It has the type qsmm_iter_t.

QSMM_HANDLE_MAP

A key-value map handle. It has the type qsmm_map_t.

QSMM_HANDLE_MSG

An error, warning, note, or uncategorized message handle. It has the type qsmm_msg_t.

QSMM_HANDLE_MSGLIST

A handle of a list of error, warning, note, or uncategorized messages. The handle has the type qsmm_msglist_t.

QSMM_HANDLE_PRG

An assembler program handle. It has the type qsmm_prg_t.

QSMM_HANDLE_RNG

A random number generator handle. It has the type qsmm_rng_t.

QSMM_HANDLE_SIDE

An interaction side handle. It has the type qsmm_side_t.

QSMM_HANDLE_STORAGE

A statistics storage instance handle. It has the type qsmm_storage_t.

QSMM_HANDLE_VEC

A handle of an ordinary or sparse vector. The handle has the type qsmm_vec_t.

QSMM_HANDLE_COUNT

The number of elements in the enumeration excluding this element.

The following union represents a handle of a specific or generic type.

Union: qsmm_handle_u

This union represents one of typed object handles or an untyped object handle. The union contains the following fields.

Field: qsmm_t qsmm

A multinode model handle.

Field: qsmm_actor_t actor

An actor handle.

Field: qsmm_actpair_t actpair

An actor pair handle.

Field: qsmm_instr_t instr

An assembler instruction handle.

Field: qsmm_iter_t iter

A key-value map iterator handle.

Field: qsmm_map_t map

A key-value map handle.

Field: qsmm_msg_t msg

An error, warning, note, or uncategorized message handle.

Field: qsmm_msglist_t msglist

A handle of a list of error, warning, note, or uncategorized messages.

Field: qsmm_prg_t prg

An assembler program handle.

Field: qsmm_rng_t rng

A random number generator handle.

Field: qsmm_side_t side

An interaction side handle.

Field: qsmm_storage_t storage

A statistics storage instance handle.

Field: qsmm_vec_t vec

A handle of an ordinary or sparse vector.

Field: void * raw_p

An untyped object handle.

The following structure holds the type of a handle along with its value.

Structure: qsmm_handle_s

This structure holds the type of an object handle and its value. The structure contains the following fields.

Field: enum qsmm_handle_e type

An object handle type.

Field: union qsmm_handle_u val

An object handle value corresponding to an object handle type in the field type.


Next: , Previous: , Up: API Basics   [Contents][Index]