General-Purpose, Asynchronous State Machine Library (upp-statemachine)

[Trilec]

Hello U++ peoples,

I would like to propose the inclusion of a new library, upp-statemachine, into the U++ framework. This is a general-purpose, asynchronous state machine designed to manage complex application logic in a clean, robust, and maintainable way. It is implemented as a traditional .h and .cpp pair.

The complete source code, along with a comprehensive GUI test harness, is available for review here:
https://github.com/Trilec/upp_statemachine

---

Why a State Machine for U++?

Many applications, from complex user interfaces to background services, are fundamentally stateful. Managing this state often involves complex chains of if/else statements, boolean flags, and scattered logic, which can be difficult to debug and extend.

A formal state machine provides a proven pattern for solving this problem. This library is designed to:

• Simplify Complex Logic: It replaces tangled conditional logic with a clear, declarative definition of states and transitions.
• Enhance Maintainability: By centralizing state management, it becomes much easier to understand application flow and safely add new features.
• Embrace Asynchronous Operations: It is built from the ground up to work with U++'s event-driven model, making it trivial to handle long-running tasks (e.g., network requests, file I/O) within a state without blocking the UI.

While it is a perfect companion for CtrlLib to manage window or dialog states, it has no dependency on GUI components and is equally powerful for console applications, server-side logic, or any long-running process.

---

Key Features & Design Philosophy

The design was guided by the U++ philosophy of creating efficient, powerful, and easy-to-use tools.

• Designed for Broad Compatibility: Care has been taken to use C++ features that are compatible with the wider U++ ecosystem, avoiding constructs that might require the very latest compilers.
• Idiomatic U++ Memory Management: The library correctly uses One<> smart pointers for managing the lifecycle of states and transitions, integrating cleanly with U++'s memory model.
• Asynchronous by Design: State entry (OnEnter) and exit (OnExit) handlers are asynchronous. They receive a done callback which they must invoke to signal completion, allowing for non-blocking, long-running operations.
• Powerful Callbacks & Guards:
  • Guard: A function that can conditionally block a transition from occurring.
  • OnBefore / OnAfter: Callbacks that fire just before and after a transition, allowing for side effects and logging.
• Built-in State History: The machine automatically tracks the transition history, enabling a simple GoBack() method to revert to the previous state—ideal for "Cancel" or "Back" button functionality.
• Minimal Dependencies: The library depends only on Core, making it lightweight and truly general-purpose.
• Clean, Modern C++ API: It uses a fluent interface with State and Transition structs, configured cleanly with lambdas for callbacks and guards.

---

Robustness and Testing

A key goal was to ensure the library is stable and production-ready. To that end, it includes a comprehensive GUI test harness (main.cpp) that validates every aspect of its functionality, including:

• Basic transitions and event handling.
• Guard and callback logic.
• History and GoBack() operations.
• Asynchronous flow control.
• Critical edge cases like re-entrant event triggers and transition failures.

This test suite serves as both a guarantee of correctness and as a rich source of usage examples.

---

Proposed Placement

Given its minimal dependency on Core and its general-purpose nature, I believe it could be a good fit within the uppsrc directory, perhaps as uppsrc/Core/StateMachine.h and .cpp. However, I am completely open to suggestions on where it would best reside within the framework's structure.

I believe this library would be a valuable addition to the U++ ecosystem.
I look forward to hearing your thoughts and feedback.
Cheers Curt

[mirek-fidler]

I think this should be in UppHub.

[klugier]

Yes, I agree with Mirek, it should be part of UppHub. We should carefully add new libraries to the main branch. Also, adding new lirbaries to UppHub is easy. If you will have any troubles, please let me know. I will help.

[izabala123]

Hi Trilec

Nice!, your library can be very useful for people who are interested in process modelling.
I also think it's best to put it on UppHub. There are very useful libraries there that help people implement specific topics. This way, the main U++ doesn't grow out of proportion. You'll see how easy it is to install it in UppHub.
It would be great if you could include a variety of examples to give an idea of what it is capable of. I am already looking forward to trying them out 😃

Best regards
Iñaki

[Trilec]

Hi Iñaki,
Thanks for the feedback!

On the point about library size, that's a great concern. Thankfully, with U++'s static linking, this adds zero overhead to an application unless a developer explicitly uses it. It's effectively 'free' to have in the toolkit for those who need it.

But my main argument is that a state machine should be a core component regardless of the animation plan. It's a fundamental tool for managing complexity, and I believe it's something developers should expect from a modern framework.

That said, this is also the first concrete step towards building our animation system. I know there have been reservations about adding 'fancy' features, and the challenge was to 'show the code' for a cheap implementation. This FSM is exactly that: the cheap, non-visual engine needed to build a modern animation system properly.

I'm committed to investing my time to help make U++ a strong contender for modern development, and I see this as a key foundational step.

I hope that clarifies my thinking!

Best regards,
Trilec

[ismail-yilmaz]

Hi Trilec,

Nice stuff. If you need any help preparing this for UppHub, let me or Kluiger know.

Best,

[Trilec]

Good point, and normally I'd agree 100% on UppHub.

My thinking here is a little different, and it's really a two-part argument. The first part is my specific plan, and the second, more important part is about the fundamental nature of a state machine in a modern framework.

First, this is step one of a two-step project for me. The next step is to build a ViewManager or AnimationManager that relies on this state machine to function. If we want that kind of feature to be nicely integrated into the core library, its foundation—this state machine—needs to be in uppsrc with it.

But more broadly, I believe providing a state machine as a core component is a powerful way to empower developers. For context, here's how some other major ecosystems approach this:

Framework / Ecosystem	Component & Location	Why This Matters
Qt (C++)	QStateMachine	Located in Qt Core, not an add-on. It's considered as fundamental as containers and is used to drive their own core animation framework. This is a direct parallel to my plan.
.NET (C#)	async/await syntax	The language itself has state machines built into the compiler. The async/await feature is literally a compiler-generated state machine, proving the pattern is essential for modern asynchronous code.
Spring (Java)	Spring Statemachine	An official, first-party top-level Spring project. It's fully integrated and supported by the maintainers of one of the world's largest enterprise frameworks.
Apple (Swift/Obj-C)	GameplayKit (GKStateMachine)	Part of Apple's own core toolkit for developers on iOS and macOS. It's provided by the platform vendor as a standard tool for managing game logic and complex UI.
JavaScript (Web)	XState Library	While a library, it has become the de-facto standard for state management in the largest developer ecosystem on the planet. It shows a clear industry trend towards adopting formal state machines for robust UI development.

My goal is to provide a tool that makes U++ more powerful and aligns it with other leading platforms. It's a strategic dependency the future, and hopefully attract more developers with its core features. (I feel I'm in this boat, as I now try to shift my development to U++, and see it with fairly fresh eyes)

I hope that provides a clearer and more compelling case for its inclusion in the main library.
What do you think?

[ismail-yilmaz]

Just my two cents:

I believe that, if implemented well, U++ could really benefit from an asynchronous state machine. While animations aren't my main concern, I'm especially interested in the socket and networking side of things.

Take a look at the Upp::HttpRequest code: it's stateful logic that can easily become complex. Refactoring it with a generic state machine would make the code cleaner, easier to maintain, and more consistent. It would also simplify implementing new technologies like Http2Request or even Http3Request.

Moreover, it would help establish a uniform and structured approach to asynchronous code across the framework, reducing duplication in future developments, whatever they may be.

[kov-serg]

Any async code should have interface:

enum { se_Init, se_Done };
struct AsyncFunction {
  void *ctx;
  int (*setup)(void *ctx,int cmd);
  int (*loop)(void *ctx);
};

1. "setup" function returns 0 on success. It must have atleast 2 commands init and done. init-initialize function, done-release all resources. In any case if init was called, there is a guarantee that done will be call at the end. Other command can be used as signals to async function (for example se_Cancel or se_Flush).
2. "loop" function returns 0 on finish and not 0 if still works. (0-done, 1-working) other values my be used as interrupt codes (for example negative values can be used as delay request). This function always return 0 if done was called.
3. all this function must not rise any exception.

Only after this the structures approach can be established.

example:

struct fn1_ctx {
  int state;
  int init() { state=0; printf("fn1.init\n"); return 0; }
  int done() { printf("fn1.done\n"); return 0; }
  int loop() {
    printf("fn1.body\n");
    return 0;
  }
  static fn1_ctx* my(void *ctx) { return (fn1_ctx*)ctx; }
  static int fn1_setup(void *ctx,int cmd) {
    switch(cmd) {
     case se_Init: return my(ctx)->init();
     case se_Done: return my(ctx)->done();
    }
    return -1;
  }
  static int fn1_loop(void *ctx) { return my(ctx)->loop(); }};
};

void sync_call(AsyncFunction &fn) {
  fn.setup(fn.ctx,se_Init);
  while(fn.loop(fn.ctx)) {}
  fn.setup(fn.ctx,se_Done);
}

Inside loop you can use coroutines or c_coroutines or a lot of if or switch or sm or any approach you want.

[ismail-yilmaz]

This is the required skeleton, yes. In the past I preferred -I still do, where applicable and make sense- (programmable) callback queue approach, using exceptions for error handling. It has an overhead but it makes things very simple.

By the way, we do have basic coroutines in UppHub (just no std=C++20 as default).

[kov-serg]

Exceptions beak execution chains and for async they are rise complexity to fast so should be avoided.
For example: batch handling with exceptions is pain.

[ismail-yilmaz]

Definitely - for true async and complex operations. Mine's were simply single-threaded non-blocking ops - socket stuff.

[kov-serg]

But callbacks may be executed on different thread, so no any guarantees. To achieve structures concurrency we need single point of control. For example if we have a lot of async functions we can place it in another async function, what will be control this group. And we give "execution" only by calling fn->loop. So a complex sheduled group of async function will looks line simple async function scheduling them inside. So we can simply iterate it like before. So this fractal look same on any scale.

Async hides a lot of complexity so interface should be as simple as possible. This skeleton factors code to independent parts, to reduce complexity. Also we could use it from external dynamic lib.

[mirek-fidler]

On the point about library size, that's a great concern. Thankfully, with U++'s static linking, this adds zero overhead to an application unless a developer explicitly uses it. It's effectively 'free' to have in the toolkit for those who need it.

Just to make things clear, we are more concerned about the amount of source code that is considered "canonical" (like core U++). It is maintainance concerns basically.

[Trilec]

Thanks all for the feedback.

Just to clarify — while this state machine is designed with UI and animation flows in mind, it's a general-purpose asynchronous tool. It works well for task orchestration, background logic, lifecycles, stateful APIs and anywhere structured state transitions help manage complexity. The goal is clean, non-blocking flow, tied into the U++ main loop — not just for look-and-feel, but for clarity and maintainability across app types.

I understand the concern about keeping upp lean. At the same time, I’d argue this FSM fills a foundational role — much like what .NET/ Qt /Redux/Swift and other modern frameworks — especially if we want to support animation and richer UI behavior natively. My intention is to build a View or Animation Manager on top of this. Splitting them into UppHub and core would fragment the architecture and create unnecessary overhead for anyone using both.

As for async interface styles — I see @kov-serg’s loop-based model is valid for service-like use cases. While the FSM here isn’t based on polling, it wouldn’t be hard to add a wrapper (e.g., monitorAdapter) for that style, if needed — without changing the core design.

// possible minimal “monitor” adapter ( rough concept)
// Lets a polling scheduler *observe* when the FSM is done.
// however It does **not** drive transitions or advance time.

enum { se_Init, se_Done };

struct FsmMonitorAdapter {
    StateMachine* fsm;                               // proposed StateMachine

    static int Setup(void* ctx, int cmd) {
        auto* self = static_cast<FsmMonitorAdapter*>(ctx);
        switch(cmd) {
            case se_Init: return self->fsm->Start() ? 0 : -1;
            case se_Done: return self->fsm->Stop()  ? 0 : -1;
            default:      return -1;                 // unsupported command
        }
    }
    // 1 = still busy, 0 = reached a terminal state
    static int Loop(void* ctx) {
        auto* self = static_cast<FsmMonitorAdapter*>(ctx);
        return self->fsm->IsBusy() ? 1 : 0;
    }
};

Caveats of this approach

Loop() is read-only: it only checks completion; it never triggers transitions or timers.
Events must still be injected elsewhere (fsm->SendEvent(...), async callbacks, etc.).
Tight polling wastes CPU and defeats the library’s non-blocking design; use timers or sparse checks if you really need this.
For background services, prefer posting events from I/O callbacks instead of busy-waiting.

In short, the adapter can integrate with a polling framework, but it’s a monitor, not a driver.

I’m happy to release this to UppHub if that’s the consensus, but feel there's a strong case for treating it as a small but strategic addition to core — especially if we want U++ to evolve toward more responsive / swipe / mobile-like GUIs.

Cheers,
Trilec

[Trilec]

Thanks for the input, @kov-serg.

Just to clarify on the point about polling in the GUI thread — while loop() may be individually cheap, the concern isn’t with the cost of a single call. It’s about the cumulative effect and architectural fit:

Polling consumes GUI thread time that would normally be used by input, painting, and callbacks. Even lightweight loop() calls can introduce visible lag when scaled across multiple components.

U++ favors an event-driven model (PostCallback, SetTimeCallback, When...) to preserve responsiveness and clarity. Relying on polling can obscure causality and lead to unnecessary CPU activity.

If periodic evaluation is needed, U++ already provides structured, non-blocking tools — timers, event hooks, etc. — without requiring a custom loop() driver.

So it’s not that polling is inherently wrong — it just doesn't align well with U++’s GUI threading model. In more complex applications, event-driven flow tends to scale better and stay maintainable.

That said, this FSM is designed to integrate naturally with U++’s async/event system. It uses transitions, callbacks, and timers that tie into the message loop — allowing responsive, non-blocking state logic without requiring polling.

I'm aiming to keep the design flexible and — as mentioned — can provide a light adapter for those who prefer polling-style observation, as long as it’s clearly optional and doesn’t imply that polling is the intended or primary model.

Cheers,
Trilec

[kov-serg]

U++ favors an event-driven model

1. Write FSMAsyncFunction
2. Write UppFSMAsyncFunctionWrapper that uses PostCallback(from background thread to feed gui message loop) or SetTimeCallback to call "loop" function from gui thread.

(2) can be used in Upp, (1) could be integrated anywhere not just Upp.

ps: This model is not only polling. You can pass into long running function (LRF) scheduler. Schedulers are complex structure. But they can be different from simple polling, fixed rate executer to more general with IO operations and controlling spawning LRF's children. LRF can use scheduler to make request, and scheduler process it and manage then to give "tick" execution resource to LRF.

[Trilec]

Thanks again @kov-serg — I do understand what you're proposing: a scheduler-driven loop model with structured long-running function control. That’s definitely effective in certain domains — e.g., low-level services, cooperative multitasking, or async I/O systems.

However, my FSM is intentionally designed around U++’s event-driven architecture, where state changes are triggered by signals, timers, or user actions — not by scheduled loop ticks. It integrates naturally into GUI apps, animation systems, and other interactive flows where transitions are async but declarative.

While I appreciate the idea of wrapping it with a loop()-style interface for system-level scheduling, reframing the core model around polling introduces several issues:

❌ It risks breaking the async flow guarantees — the done() lifecycle becomes unclear

❌ It may block or overload the GUI thread if misused

❌ It fragments the design intent — making it harder to reason about flow, especially in UI and animation contexts where timing and responsiveness are critical

So yes — your model is valid for background or IO service logic. But this FSM is purpose-built for reactive UI behavior, animation, and interaction. Recasting it as a scheduler unit isn’t just a stylistic change — it shifts the architecture away from the actual problems this tool is designed to solve.

As mentioned, I have no problem keeping the interface flexible through optional adapters — that could help in service-like scenarios. But at the risk of going in circles: the design focus here is deliberate and carefully considered.

[kov-serg]

I just pointing on structured approach for single thread asyncfunction.
How you intend to decompose complex FSM, to achieve hierarchical fsm. For example L0 fsm handle emergency events and safely lands moving parts in place in case of emergency signal and L1 fsm processing main functionality, L2 fsms controlling various complex motions and so on. In case where we can explicit control over "ticks/clock/loop" we can easily control and reuse children asyncfunction. But in case of flat FSM graph builder through state/transition we have to handle all fails for each state again and again. This significantly rises complexity of graph. Especially then modify/refactoring graph introducing new states.

ps: debuging is much easier for small simple asyncfunction combined into more complex. Because you can test all parts independently in virtual environment and virtual time.

[Trilec]

Thanks again @kov-serg — I get what you're suggesting.

You're talking about a structured loop model that’s good for layering async functions and building hierarchical FSMs with fine control. However, this really depends on the use case — and I think that’s where I’m trying to make a clear distinction.

In UI or animation contexts, it’s often clearer to keep failure handling local to each state, since the response is usually tied to what the user sees or does at that point. Centralizing it can make things harder to follow.

But in service-style systems, I agree — having shared fallback logic at a higher level can definitely help keep things cleaner and more reusable.

So yeah, different goals, different models.

And in this case, the service-style system isn’t the direction I’m building for. If you want to put something together for the service/task loop case using an adapter — great, there are enough hooks. I’m happy to help where I can.

[Trilec]

Hi all — just checking in.

I’d like to move forward on this now. From my side the design’s settled and seems stable enough for a PR — unless anyone has strong objections, happy to prep it for submission.

Let me know if that sounds okay.

Cheers,
Trilec

[Trilec]

@mirek-fidler — if you're happy, I’d love to move ahead with a merge while my development window’s still open. Appreciate the consideration.

Cheers,
Trilec

[Trilec]

mmm ... does @mirek-fidler check github? or should I place in the forum?

[klugier]

Trilec, I suggest moving forward with your changes. We can not allow ourself to lose your development window :)

My suggestion for now is to create them as UppHub package and see how they work. If everything will be fine, we can consider moving them under this repository umbrella. The main problem I see at the moment is that Mirek might not be 100% into these changes and considering something different. It happened in the past for example when I provided changes for clang-format. In the end the implementation was different in 70-80%.

Also, what Mirek might don't like is that we are duplicating solutions from other frameworks. I don't say it is a bad thing. But, to be competitive we might need something more innovative. In addition to that, your state machine might not be in accordance with framework philosophy and we might ended with something else. Last but not least is additional maintenance cost. In the end Mirek will need to maintain the new code. So, he is very careful with that and he is tending for very simple solutions over complex one.

Anyway, the safest starting point is to put state machine and easing as a two separate UppHub packages. There will be no problems with publishing them.

[Trilec]

k, I’ll give that a shot,

On a side note, I’m feeling a bit deflated—4+ weeks on FSM and Curve debates and almost a year before animation got traction. I totally get the maintenance concerns, but in my heart I hoped for more openness around ideas to modernize U++. If core modernization really isn’t on the roadmap its best I slowly fade back into the shadows.

Cheers Trilec

[klugier]

I totally understand your point of view. I also agree that we should move forward more rapidly. You know what, maybe it would be better if your prepare PR against this repository. If you can do it in chunks, FSM and Easing should have separate PRs, if not possible do one big PR. I think this should also help Mirek do the final decision and adapted your code if needed. In general from my point of view your code looks fine, I assume I will have some remarks, but this will be on code review level.

Sorry for my previous message, I would like to say that we appreciate all the contribution and we definitely need more of it. I am also glad for your work in other areas such as creating exemplary repositories that are basing on U++.

[Trilec]

Thanks for the support @klugier.
State Machine – Final Implementation & Test Suite

Core FSM is finished: cleaned up the code, converted all comments to the U++ style, and polished the API.
Comprehensive tests added in uppsrc/CoreTests/StateMachineTest.cpp, covering:

    Basic transitions
    Guards & callbacks
    History & GoBack
    Async flow
    Edge cases (re-entrant, failure paths)
    Stress test (rapid GoBack/trigger)

All tests are passing (see screenshot above).

Next steps:

Publish an UppHub package so folks can grab it immediately. (Where I figure out how)

Feel free to review here [ github.com/Trilec/upp_statemachine ]

Cheers,

[ismail-yilmaz]

@Trilec ,

Thank you for your efforts.
I will review the package for UppHub, ASAP.
So far I see only minor issues, which I'll let you know.

Cheers.