Question About Using QASM_IS_IN() Without Q_SPY

[kzorer]

Hello,

I have a question regarding the usage of QASM_IS_IN() / QHsm_isIn_() in QP/C.

I noticed that QASM_IS_IN() is only available when Q_SPY is enabled:

#ifdef Q_SPY
    #define QASM_IS_IN(me_, stateHndl_) \
        (*((QAsm *)(me_))->vptr->isIn)((QAsm *)(me_), (stateHndl_))
#endif

Internally, this calls QHsm_isIn_():

bool QHsm_isIn_(QAsm * const me,
    QStateHandler const stateHndl)

My use case is very simple:
I would like to check whether an HSM is currently inside a specific state (or substate hierarchy) during runtime, for example:

if (QASM_IS_IN(&myHsm.super, &SomeState)) {
    ...
}

However, I do not want to enable Q_SPY in production builds just to use this functionality.

I also noticed comments in the headers mentioning that this API is protected/private/internal, so I wanted to ask:

1. Is there any technical or architectural reason why QASM_IS_IN() is restricted to Q_SPY builds?
2. Is using QHsm_isIn_() directly considered unsafe or unsupported?
3. Is there a recommended public API for checking the current state/substate membership of an HSM?
4. Would it be acceptable to expose QASM_IS_IN() outside of Q_SPY, or is there a hidden invariant/performance concern behind this design?

From reading the implementation, it seems to only walk the superstate hierarchy and restore the invariant afterwards, so I wanted to understand whether there are any side effects or design reasons I might be missing.

Thank you.

[quantum-leaps]

Hi kzorer,

The “is‑in‑state” query is intentionally restricted because it is problematic in most real‑world uses. The rationale is documented in the description of QASM_IS_IN():

The macro is available only for tracing/testing (when Q_SPY is defined) to prevent several incorrect or unsafe uses of the “is‑in” query.

The core issues are:

Querying a state machine’s own state at runtime is almost always a design error.
During a transition, the “current state” is not well‑defined—entry/exit sequences and superstate unwinding may be in progress. Using isIn() as a guard condition inside the same HSM leads to ambiguous or misleading results.

Querying another concurrently executing HSM is unsafe.
Its state may change asynchronously, and it may also be mid‑transition. There is no stable, externally observable “current state” unless you explicitly model and publish it.

The query requires exposing state handlers.
That breaks encapsulation and couples external code to internal implementation details of the HSM.

For these reasons, QASM_IS_IN() is intentionally exposed only in Q_SPY builds, where it is used for tracing, testing, and verification—not for production logic.

Regarding your specific example:

if (QASM_IS_IN(&myHsm.super, &SomeState)) {
    ...
}

This pattern is unnecessary and semantically meaningless inside the HSM itself. The state machine already knows which state it is in. The result of the query is therefore trivial: it returns true for the current state (or any of its superstates) and false for all others. It provides no information that the HSM does not already possess by construction.

If your design requires other components to know the HSM’s externally visible mode or status, the recommended pattern is:

• Model that information explicitly as part of the HSM’s state data, and
• Publish it via events.

This preserves encapsulation, avoids mid‑transition ambiguity, and gives you a stable, well‑defined interface.

So to your direct questions:

• Is there a technical reason QASM_IS_IN() is restricted to Q_SPY? Yes—preventing unsafe or semantically invalid uses.
• Is calling QHsm_isIn_() directly supported? No. It is an internal API and not guaranteed to remain stable.
• Is there a recommended public API? No. The recommended design is to model and expose the externally relevant mode explicitly, rather than querying internal state handlers.
• Would it be acceptable to expose QASM_IS_IN() in production? Not recommended. It breaks encapsulation and encourages designs that rely on undefined or unstable state during transitions.