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