Polyrole is a multi-role state machine library built on Zig's type system. A protocol is a deterministic state graph: states are tagged unions, transitions are type parameters, and each role's behavior is dispatched by its role. Roles may run in one thread, in separate threads, or across a network; communication is isolated behind replaceable channels.
A state is a union(enum) whose fields are the possible messages. Data(Payload, NextState) carries the payload and names the state to enter after the message moves:
const Ping = union(enum) {
ping: Data(i32, Pong),
next: Data(void, NextState),
};
const Pong = union(enum) {
pong: Data(i32, Ping),
};Every state also carries info: sender and receiver, while @TypeOf(info) holds the protocol-wide internal_roles and extern_state.
symmetric_run drives one role:
- sender: calls
processto produce the message, sends it to everyreceiver, then advances to the message'sNextState. - receiver: receives the message, calls
preprocess_N(N is its position inreceiver), then advances. - non-participant: executes nothing and waits for a
Notifythat moves it to the next state.
Each role therefore follows one deterministic path through the graph.
The protocol does not depend on networking: simulate runs every role in one thread without channels, symmetric_run adds channels, and RoleRunner exposes one step so an event loop or scheduler can drive it.
A state with more than one union field is a branch, and only the sender knows which one was chosen. The library therefore requires 1 + receiver.len == internal_roles.len: every other internal role must receive the message, so none can miss the new state.
When the next state is in extern_state (or is Exit), internal_roles[0] sends Notify to every role outside internal_roles, and those roles jump to the new state. Protocol hand-over stays synchronized without polling.
A protocol composes by using another protocol's entry state as a NextState:
charlie_as_coordinator: Data(void,
PingPong(.alice, .bob, PingPong(.bob, .charlie, CAB(@This()).Begin).Ping).Ping),At compile time reachableStates expands the nesting into one state graph and validates it: senders and receivers belong to internal_roles, receivers exclude the sender and are unique, branch states satisfy the notification rule, and every state shares the same per-role context types. A protocol that compiles is a legal state machine.
A top-level Context gives each role one field holding everything that role needs, and handlers receive that field through info.Ctx(role). Protocols share a role's data without open-coding globals.
Requires Zig 0.17.0.
zig fetch --save git+https://github.com/sdzx-1/polyrole.gitThen in build.zig:
const polyrole = b.dependency("polyrole", .{ .target = target, .optimize = optimize });
exe_mod.addImport("polyrole", polyrole.module("root"));const polyrole = @import("polyrole");zig build pingpong — Alice and Bob exchange a counter until the protocol exits. Two states point at each other, and a next branch leaves the loop.
The protocol lives in examples/protocols/pingpong.zig, with the entry point in examples/pingpong.zig.
zig build sendfile — Alice streams a file to Bob over TCP in 4 KB chunks and sends a hash every 20 MiB; Bob verifies it.
The Send state loops on itself for streaming, and CheckHash(Success, Failure) is a parameterized state template reused for checkpoints and the final chunk.
See examples/protocols/sendfile.zig and examples/sendfile.zig.
zig build 2pc — Charlie coordinates a transaction between Alice and Bob; both vote randomly, and the coordinator commits, retries, or aborts.
See examples/protocols/two_phase_commit.zig and examples/2pc.zig.
zig build random-pingpong-2pc — a Selector picks one of three composite paths for 300 rounds, each chaining pingpong exchanges into a two-phase commit with a different coordinator.
See examples/random_pingpong_2pc.zig and examples/protocols/.