1.10.2 Basic Datatypes and Macros

The basic notion used in QSMM is signal. Signals are parts of an argument of a probabilistic mapping. A result of a probabilistic mapping is also a signal. Signals are the carriers of actions. In QSMM, non-negative integers identify signals. The maximum possible value of a signal identifier depends on a datatype used to hold the identifier. As the number of possible signals can be critical for a particular application, special datatypes exist for signal identifiers. The header file sig.h included in qsmm.h and err.h defines those datatypes.

Data type: qsmm_sig_t

This is an unsigned integer datatype for storing signal identifiers and the numbers of signals. The set of allowed values for this datatype is the range 0 to QSMM_SIG_MAX+1 and the special value QSMM_SIG_INVALID. The current implementation defines the datatype as unsigned int.

In principle, a developer can define this datatype as a smaller unsigned integer type to reduce memory consumption. Corresponding modification of definitions of qsmm_ssig_t datatype and QSMM_SIG_MAX, QSMM_SIG_INVALID, QSMM_FMT_PRI_SIG, QSMM_FMT_PRI_SSIG, and QSMM_FMT_SCN_SIG macros (see below) may be necessary. As of QSMM version 1.17, the developer may not define this datatype as a larger unsigned integer type, because not all package source code has been reworked to support such a type.

The values QSMM_SIG_MAX+1 and QSMM_SIG_INVALID must lie in the range of allowed values of size_t type. This restriction means that the condition “sizeof(qsmm_sig_t)<=sizeof(size_t)” holds true.

Data type: qsmm_ssig_t

[New in QSMM 1.17] This is a signed integer datatype for storing signal identifiers and the numbers of signals. The set of allowed values for this datatype is the range -(qsmm_ssig_t) QSMM_SIG_MAX-1 to QSMM_SIG_MAX+1 and the special value QSMM_SIG_INVALID. The current implementation defines the datatype as int. Specifics of defining this datatype as a different signed integer type are the same as for the datatype qsmm_sig_t. The condition “sizeof(qsmm_ssig_t)==sizeof(qsmm_sig_t)” must hold true.

Signal identifiers not only specify signals themselves but also other entities internally represented by signals. For example, the identifiers of nodes of a multinode model and their states are signal identifiers.

Use the following macros when working with signal identifiers.

Macro: QSMM_SIG_INVALID

Represents an invalid signal identifier. Use it as a substitute for the NULL value of a signal identifier because identifier 0 is valid one. Historically, the macro expands to an unsigned integer value. In QSMM version 1.17, the macro expands to ((1 << (sizeof(qsmm_sig_t)*8-1))-0U).

Macro: QSMM_SIG_MAX

This is the maximum allowed value of a signal identifier. Historically, the macro expands to an unsigned integer value.

Consider two affirmations:

1. When an array contains information on signals with identifiers in the range 0 to QSMM_SIG_MAX, the number of elements in the array is equal to QSMM_SIG_MAX+1.
2. When the upper bound of a range of signal identifiers is not inclusive, the range x to QSMM_SIG_MAX has upper bound QSMM_SIG_MAX+1.

To make it possible to use the datatypes qsmm_sig_t and qsmm_ssig_t for specifying the numbers of signals in the first case and signal ranges with not inclusive upper bounds in the second case, those datatypes additionally support storing value QSMM_SIG_MAX+1. The datatype qsmm_ssig_t additionally supports storing value -(qsmm_ssig_t) QSMM_SIG_MAX-1. In QSMM version 1.17, the macro expands to ((1 << (sizeof(qsmm_sig_t)*8-1))-2U).

Macro: QSMM_FMT_PRI_SIG

[New in QSMM 1.17] An optional length modifier and a conversion specifier in format strings for functions similar to printf for printing values of qsmm_sig_t type. The macro expands to ‘u’.

Macro: QSMM_FMT_PRI_SSIG

[New in QSMM 1.17] An optional length modifier and a conversion specifier in format strings for functions similar to printf for printing values of qsmm_ssig_t type. The macro expands to ‘d’.

Macro: QSMM_FMT_SCN_SIG

[New in QSMM 1.17] An optional length modifier and a conversion specifier in format strings for functions similar to scanf for parsing values of qsmm_sig_t type. The macro expands to ‘u’.

A developer should use the aforementioned datatypes and macros to write source code supporting easier adaptation for a smaller or larger number of possible signals. The source code will also be better compatible with future versions of QSMM framework.

Below there is an example of using the datatype qsmm_sig_t and the macro QSMM_FMT_PRI_SIG. The function print_sig_array prints an array of signal identifiers specified by a pointer to the array and a number of its elements.

#include <stdio.h>
#include <qsmm/qsmm.h>

void
print_sig_array(
    const qsmm_sig_t *sigp,
    qsmm_sig_t nsig
) {

    putchar('[');
    for (qsmm_sig_t idx=0; idx<nsig; idx++) {
        if (idx) fputs(", ",stdout);
        printf("%" QSMM_FMT_PRI_SIG,sigp[idx]);
    }
    puts("]");
}