Troupe：multi-role finite state machine

sdzx-1 · November 16, 2025, 1:12am

Multi-role finite state machine, used for multithreaded programs or distributed programs.

The behaviors of multiple characters are orchestrated into a state machine. Imagine a theater with many characters performing a play. The behaviors of all characters are arranged as a whole in the script. When a certain message is sent, everyone will complete their performance according to the script.

Some similar libraries:

This project was initially called “polysession,” and I only intended it for developing multi-role communication protocols.

However, I later discovered its uses extend far beyond communication protocols. For example, you can use it to create game scripts and write multi-threaded programs.

When there is only one participating role, troupe is equivalent to polystate. Or, you can consider polystate as a special case of troupe.

sdzx-1 · November 16, 2025, 1:28am

The troupe allows you to construct the overall control flow of your program through declarative composition and generates the overall control flow diagram through the compiler.

github.com/sdzx-1/troupe

examples/random_pingpong_2pc.zig

74b00bdaf


      
          pub const Start = union(enum) {
              charlie_as_coordinator: Data(void, PingPong(.alice, .bob, PingPong(.bob, .charlie, PingPong(
                  .charlie,
                  .alice,
                  CAB(@This()).Begin,
              ).Ping).Ping).Ping),
              alice_as_coordinator: Data(void, PingPong(.charlie, .bob, ABC(@This()).Begin).Ping),
              bob_as_coordinator: Data(void, PingPong(.alice, .charlie, BAC(@This()).Begin).Ping),
              exit: Data(void, troupe.Exit),

For example, the above definition will generate the following control chart:

The effect during runtime:
GIF 2025-11-16 09-27-54

tholmes · November 17, 2025, 8:09pm

I don’t understand it at all, but from your descriptions it seems like something sublime

sdzx-1 · February 10, 2026, 8:55pm

The stacked coroutines have been merged into master.

A troupe is a framework describing multi-role communication. Using evented, we’ll use one million pairs of pingpong protocols, representing two million fibers.

Each pair of fibers in the pingpong protocol will send messages to each other 30 times.

github.com/sdzx-1/troupe

examples/pingpong.zig

b76da867a


      
              bob: type = BobContext,
          };
          
          pub const EnterFsmState = pingpong.MkPingPong(Role, .alice, .bob, Context{}, .pingpong, .pingpong, ps.Exit).Ping;
          
          pub const Runner = ps.Runner(EnterFsmState);
          pub const curr_id = Runner.idFromState(EnterFsmState);
          
          const QueueChannel = @import("channel.zig").QueueChannel;
          
          pub fn main(init: std.process.Init) !void {
              const gpa = init.gpa;
          
              var evented: std.Io.IoUring = undefined;
              try evented.init(gpa, .{ .environ = init.minimal.environ });
              const io = evented.io();
          
              var atomic_val: std.atomic.Value(u32) = .init(0);
          
              var group: std.Io.Group = .init;

zig build pingpong --release=fast

It took about 10 seconds to complete on my PC.

ps: I set the value of A here to 1 * 1024.

invlpg · February 10, 2026, 10:03pm

It doesn’t have networking yet, but for anything needing concurrency for local IO, it seems to be there and working reasonably okay.

Unless you’re debugging IoUring.zig itself, I’d recommend adding the following to your root module as it currently has some quite verbose debug logging.

const std_options: std.Options = .{
    .log_scope_levels = &.{ .{ .scope = .@"io-uring", .level = .info } },
};

Not the author of it, just someone who has been following development closely and been toying around with it since the PR was made a little while ago.