---

1.10.3 Object Handles ¶

Object handles reference various objects created by the QSMM library. A handle is a typed pointer to a QSMM internal structure. The type of a handle corresponds to the type of an object referenced by the handle. Except for handles of qsmm_mehcall_t type, a program that uses the QSMM library cannot examine or change the content of the internal structure by methods other than calling API functions taking a handle of the corresponding type as an argument. Except for handles of qsmm_mehcall_t type, 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 manual section with an object description.

Handle Type	Object Type	Reference to a Section in This Manual
qsmm_t	multinode model	Creating a Multinode Model
qsmm_actor_t	actor	Creating an Actor
qsmm_actpair_t	actor pair	Creating the Model Instance
qsmm_instr_t	assembler instruction	Basic Datatypes
qsmm_iter_t	map iterator	Part of C implementation of functionality of STL map and multimap templates. See Creating Maps and Iterators.
qsmm_map_t	map	Part of C implementation of functionality of STL map and multimap templates. See Creating Maps and Iterators.
qsmm_mehcall_t	model event handler call	Event Handler Call Parameters
qsmm_msg_t	message	Creating Messages
qsmm_msglist_t	message list	Creating a Message List
qsmm_prg_t	assembler program	Basic Datatypes
qsmm_rng_t	random number generator	Creating a Random Number Generator
qsmm_side_t	interaction side	Part of Side API. See Registering Interaction Sides.
qsmm_storage_t	statistics storage	Storage Handle
qsmm_vec_t	vector	Ordinary 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 the handles do not reference interrelated objects (e.g. when an object is a component of another object). However, calling API functions for the same handle 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

The special value denoting 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_MEHCALL

The handle of a model event handler call. The handle has the type qsmm_mehcall_t.

QSMM_HANDLE_MSG

The handle of an error, warning, note, or uncategorized message. The handle has the type qsmm_msg_t.

QSMM_HANDLE_MSGLIST

The 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

The 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_mehcall_t mehcall ¶

The handle of a model event handler call.

Field: qsmm_msg_t msg ¶

The handle of an error, warning, note, or uncategorized message.

Field: qsmm_msglist_t msglist ¶

The 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 ¶

The 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.