Next: Error Handling, Previous: Basic Datatypes and Macros, Up: API Basics [Contents][Index]
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 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 for Assembler Programs. |
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_msg_t | message | Creating Messages. |
qsmm_msglist_t | message list | Creating a Message List. |
qsmm_prg_t | assembler program | Basic Datatypes for Assembler Programs. |
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 Types. |
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 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.
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.
This union represents one of typed object handles or an untyped object handle. The union contains the following fields.
A multinode model handle.
An actor handle.
An actor pair handle.
An assembler instruction handle.
A key-value map iterator handle.
A key-value map handle.
An error, warning, note, or uncategorized message handle.
A handle of a list of error, warning, note, or uncategorized messages.
An assembler program handle.
A random number generator handle.
An interaction side handle.
A statistics storage instance handle.
A handle of an ordinary or sparse vector.
An untyped object handle.
The following structure holds the type of a handle along with its value.
This structure holds the type of an object handle and its value. The structure contains the following fields.
An object handle type.
An object handle value corresponding to an object handle type in the field type
.
Next: Error Handling, Previous: Basic Datatypes and Macros, Up: API Basics [Contents][Index]