state: automatic serialization of a processor's state struct

[jcelerier]

Serialize a processor's persistent state by reflecting over a state struct, the way the value bindings already reflect over inputs and outputs -- no hand-written byte code.

struct MyProcessor
{
  struct { … } inputs;
  struct { … } outputs;
  struct { std::vector<uint8_t> program; int mode{}; std::string label; } state;
};

The presence of the state member is enough; avnd::save_object_state / load_object_state do the rest. This is the core only -- concepts, the serializer and its tests. Wiring it into the CLAP and VST3 state containers is a follow-up.

What is covered

Member types are classified with the same concepts the value bindings use (avnd/concepts/generic.hpp), so anything a processor can carry round-trips: scalars and enums, strings, vector and other list containers, set and map, optional, variant, pair and tuple, std::array, aggregates, and any nesting of those. Verified on GCC 16 and MSVC across 21 type combinations.

Refused at compile time: anything that only borrows its data -- a pointer, reference or string_view -- since it would be written out as an address that means nothing to the process reading it back. A processor needing one provides save/load on its state instead, which takes precedence over reflection.

Format and schema changes

Members are encoded positionally, each as a self-describing record [tag][scalar kind][size][payload], behind a header carrying a format marker, a layout hash and the field count. The shape of the data absorbs the common edits without any version bookkeeping:

• appending a member: older data just has fewer records, the new member keeps its default;
• dropping a trailing member: its record is skipped;
• changing a member's type: the record no longer matches, so it is skipped rather than reinterpreted -- the scalar kind distinguishes an int from a float of the same width.

An edit the format cannot follow on its own -- reordering or inserting in the middle -- changes the layout hash and is refused unless the processor declares a state_version and a migrate_state hook, which is also how a change of meaning (same type, new unit) is handled. Data written by a newer version than the binary understands is refused rather than misread.

The one edit nothing here can see is a swap of two members of the identical type; that is exactly what the version bump exists for, and it is documented as such. In practice this suggests the same discipline as inlets: add state members at the end.

Override and versioning

// full control of the bytes -- takes precedence over reflection
struct { std::vector<uint8_t> save() const; bool load(const uint8_t*, std::size_t); } state;

// or reflect, with a migration for the changes reflection cannot follow
halp_meta(state_version, 3)
static void migrate_state(auto& state, int from) { … }

Testing

test_state_serial and test_state_object: the round-trip, the full type surface, the schema-change matrix (append / drop / retype / reorder), truncated and corrupt input, and the override and migration paths. All pass on MSVC; the type-coverage matrix was also run on GCC 16. FindBoost was not touched here (it lives in the transport/state PR).

🤖 Generated with Claude Code