Flags

While the Stow can be used to share state across modules. Individual modules often need to keep track of local state. In many cases, local state can be boiled down to a series of state flags. Gantry provides tooling to easily create and validate module state flags.

Flags are represented as atomic bitfields used for tracking module state. They support optional compile-time-defined rules that are validated at runtime whenever a flag changes.

Defining Flags

Use FLAGS_DEFINE to declare a named bitfield along with any validation rules. Pass NO_FLAG_RULES if you don’t need rules.

FLAGS_DEFINE(
    conn_flags,
    (CONN_OPEN, CONN_AUTHENTICATED, CONN_ERROR),
    FLAG_REQUIRES(CONN_AUTHENTICATED, CONN_OPEN)
    FLAG_EXCLUSIVE(CONN_OPEN, CONN_ERROR)
);

In this example, CONN_AUTHENTICATED is only valid if CONN_OPEN is set. CONN_OPEN and CONN_ERROR cannot both be set at the same time.

Setting and Checking Flags

SET_FLAG(conn_flags, CONN_OPEN);

if (CHECK_FLAG(conn_flags, CONN_AUTHENTICATED)) {
    // ...
}

CLEAR_FLAG(conn_flags, CONN_OPEN);

All operations are atomic and thread-safe.

Validation Rules

Rules are checked after every SET_FLAG or CLEAR_FLAG when runtime validation is enabled.

FLAG_REQUIRES(A, B)

Asserts that if flag A is set, flag B must also be set.

FLAG_EXCLUSIVE(A, B)

Asserts that flags A and B are never both set at the same time.

When CONFIG_FLAGS_VALIDATION=y, validation rules run inline in the call that changed the flag. An assertion failure halts execution, making invalid flag states immediately visible during development.

Configuration

CONFIG_GANTRY_FLAGS=y
CONFIG_FLAGS_VALIDATION=y # defaults to on in DEBUG builds

API Reference

FLAGS_DEFINE(name, flags, rules)

SET_FLAG(name, flag)

CLEAR_FLAG(name, flag)

CHECK_FLAG(name, flag)

FLAG_REQUIRES(flag1, flag2)

FLAG_EXCLUSIVE(flag1, flag2)