Forem: Matti | funkyposts

When One Shell Isn’t Enough: Scaling the Functional Core–Imperative Shell Pattern with Actors in C++

Matti | funkyposts — Fri, 10 Apr 2026 08:15:26 +0000

How to structure growing C++ systems into multiple actor-driven core–shell pairs

The previous post showed how the functional core–imperative shell pattern separates code into a pure part where the business logic is implemented and an effectful part that calls the pure one and handles its side effects. In consequence, the shell must handle all side-effects of the application.

But as the application grows, handling different kinds of side effects (IO, state, timers) for the entire system in a single place quickly becomes problematic. Too many unrelated concerns end up in one central hub, making the code harder to reason about and maintain.

Which raises the crucial question: how do we scale the functional core–imperative shell pattern?

The Design Idea: Actors as Shell

In order to keep things clean, we need to decouple unrelated shell responsibilities. Thus, a single shell isn’t enough—we need multiple ones, each focusing on a subset of side effects to be handled.

To fully understand what this means, let’s look at this design from the business logic point of view: effectively, the business logic is split into multiple cores, each with its own shell that handles only the side effects it requires.

To put this idea into practice, the actor model is perfectly suited, thanks to its ability to encapsulate state and localize side effects. The idea is simple: combine the actor model with the functional core–imperative shell pattern and implement shells as actors. This allows multiple shells to coexist cleanly while still being able to interact easily with one another.

A Real-World Example

Let’s see this design in action with an example from my funkysnakes project. I prototyped the actor implementation there on top of the Asio framework. It's quite lean although it has similar semantics to ROS2 in terms of topic based message passing.

However, the funkysnakes game implementation is distributed across multiple actors, each following the core–shell pattern as described above.

Let's focus on two actors that are connected by a topic that communicates the DirectionMsg, representing a requested direction for the player's snakes.

enum class Direction { UP, DOWN, LEFT, RIGHT };

struct DirectionMsg {
    PlayerId player_id;
    Direction direction;
};

This message is published by the InputActor that is responsible for handling user input once a player presses a direction key.

class InputActor : public Actor<InputActor> {
    public:
        InputActor(ActorContext ctx, 
                   TopicPtr<DirectionMsg> direction_topic)
        : Actor{ctx},
          direction_pub_{create_pub(std::move(direction_topic))} {}

    private:
        void processInputs() {
            while (auto ch = stdin_reader_->tryTakeChar()) {
                auto [key, new_state] = tryParseKey(*ch, key_parser_state_);
                key_parser_state_ = new_state;

                if (key) {
                    auto direction_msg = tryConvertKeyToDirectionMsg(*key);
                    if (direction_msg) {
                      direction_pub_.publish(*direction_msg);
                    }
                }
            }
        }

        PublisherPtr<DirectionMsg> direction_pub_;
};

The GameEngineActor receives the DirectionMsg message and applies it to its game state game_state_. Once the game_loop_timer_ triggers, the snakes are moved forward based on the latest direction. The processing of actor inputs like messages or timer events is coordinated in the processInputs method, which is invoked whenever an input arrives.

class GameEngineActor : public Actor<GameEngineActor> {
    public:
        GameEngineActor(ActorContext ctx, 
                        TopicPtr<DirectionMsg> direction_topic,
                        TimerFactoryPtr timer_factory)
        : Actor(ctx),
          direction_sub_(create_sub(direction_topic)),
          game_loop_timer_(create_timer<GameTimer>(timer_factory)) {}

        void processInputs() override {
            if (auto direction_msg = direction_sub_.tryTakeMessage()) {
                // applies direction to game_state_ by calling the related pure function of the core here
            }

            if (auto elapsed_event = game_loop_timer_.tryTakeElapsedEvent()) {
                // moves snakes forward by calling the related pure function of the core here
            }
        }

    private:
        SubscriptionPtr<DirectionMsg> direction_sub_;
        GameLoopTimerPtr game_loop_timer_;
        GameState game_state_;
};

In summary, the InputActor asynchronously publishes player direction updates, while the GameEngineActor consumes them and evolves the game state each time the game loop timer fires.

Why this scales

Of course, this modular design comes with some benefits, let's take a closer look:

Separation of Concerns: Clear Responsibilities and Independent Module Interfaces
The input handling and game logic are completely decoupled. Each actor has a narrow, focused responsibility. The DirectionMsg forms their connection point which is independent of any specific actor, so the modules don’t depend on each other directly—they only agree on a shared data contract. This keeps the boundaries clean and prevents any form of tight coupling.
Simplified Reasoning: Localized Complexity
Complexity is distributed across multiple shells. Each shell only handles its own side effects. The GameEngineActor doesn't care about publishing direction messages, and the InputActor doesn't deal with the game state or the game loop timer. Each part remains small and understandable.
Fewer Bugs: Concurrency and Isolation
Processing key events and running the game loop happen asynchronously. Key events occur sporadically, while the game loop runs periodically via a timer. Each actor has its own single-threaded execution environment and processes events such as incoming messages or timer expirations sequentially. This eliminates low-level multithreading issues such as data races, because there is no shared mutable state and therefore no need for manual synchronization. Anyone who has spent days debugging low-level multithreading issues knows how valuable such a design is.
Better Maintainability: Independent Scaling
You can add another input source, such as a Bluetooth controller, without touching the GameEngineActor. You can even add it without touching the existing InputActor, just adding another actor that publishes a DirectionMsg message. Each module evolves independently.

Key Advantage: Bridging by Design

Actually, there is another very important benefit that goes beyond modularity: The actor-based functional core–imperative shell design is able to bridge naturally functional and non-functional code via inter-actor communication. So, the same way actors implemented as shell-core pairs can interact with each other they can also interact with actors implemented in traditional OOP design. This is actually game-changing. You can build a single application that combines traditional OOP design with functional design, with clear boundaries between them. It's not a compromise—it's straightforward design: you choose which actor should follow which design based on your needs and the architecture just supports you there.

Where we arrived at

The functional core – imperative shell pattern scales by structuring the system into multiple core–shell pairs. This decouples unrelated concerns like handling input and advancing game state. In addition, this actor-based separation enables a clean bridge between traditional object-oriented design and a functional approach.

Sure, introducing actors is not for free. The extra abstraction and message passing bring additional complexity that needs to be balanced against the advantages.

However, if you choose this architecture, you get a strong foundation for building modular applications while being able to bridge programming paradigms. In practice, I’ve found the flexibility to incrementally apply functional design where it makes sense extremely valuable—you might agree.

Outlook

This and the previous post touched on state handling, but only at a high level as part of the shell. At the same time, the core needs to read and evolve that state.

Designing clean interfaces for core functions requires a deeper understanding of the underlying mechanics. In the next post, I will take a closer look at state management and how to handle it effectively.

Part of the funkyposts blog — bridging object-oriented and functional thinking in C++.
Created with AI assistance for brainstorming and improving formulation. Original and canonical source: https://github.com/mahush/funkyposts (v01)

Handling Side Effects in Modern C++: Interfacing Pure Functions with Our Imperative World

Matti | funkyposts — Thu, 26 Mar 2026 21:17:57 +0000

Introducing the functional core–imperative shell pattern

The previous post clarified why structuring business logic as pure functions makes code easier to test and reason about. But when you try to utilize pure functions, you quickly run into a problem: Although you don't want your functions to have side effects, the application you are building still must perform effectful operations to be useful. These include IO, updating state, or reacting in a time‑based manner. This leads to a practical question: how can effect‑free functions ultimately cause the effects an application must perform?

Decoupling Logic and Side Effects

The high‑level answer is surprisingly simple: pure functions let someone else perform side effects for them. Therefore, they return data describing what should happen, and it's the caller that interprets the result and performs the effects. So, effect‑related behavior still happens—it’s just moved to the call site. For example, a pure function decides to create a log message, and the caller interacts with the outside world by printing it to stderr.

If this reminds you of the command pattern, you’re not wrong—but here it’s about how you organize the system. The key idea is to introduce two complementary worlds: one where pure code requests effects and one where imperative code performs them.

The Functional Core–Imperative Shell Pattern

This simple structure is called functional core–imperative shell. It splits an application into a functional core (pure business logic) and an imperative shell (which calls the core and performs side effects).

Imperative Shell: For a C++ developer this part is familiar. Here anything effectful is allowed: using the standard library to write to stderr, using protocol stacks to communicate with other systems, mutating private members to maintain state, or managing timers. In addition, the shell is responsible for managing the application’s execution environment, such as setting up concurrency. The only constraint is: don’t implement business logic here.

Functional Core: Every business decision is encoded in pure functions. These functions together form the core. You can compose them freely, while these compositions remain pure. This lets you build various layers of abstraction and organize the business logic cleanly.

One important design aspect I want to highlight: the core is self‑contained. So, while the shell depends on the core, the core is independent of the shell. This enables testing the core in complete isolation from any shell.

This is exactly where utilizing pure functions pays off: testing becomes straightforward: you call the function with input values and verify the result. There’s no heavy mocking, no dependency injection, and no complex setup.

Applying the Pattern in C++

Let's look at a simplified C++ example from a snake game to see core and shell clearly. Consider direction change validation — the rule that prevents instantly reversing direction.

enum class Direction { Up, Down, Left, Right };
enum class SoundEffect { None, InvalidInput };

struct EvaluationResult {
    bool direction_changed;
    SoundEffect sound_effect;
};

Direction opposite(Direction d) {
    switch (d) {
        case Direction::Up: return Direction::Down;
        case Direction::Down: return Direction::Up;
        case Direction::Left: return Direction::Right;
        case Direction::Right: return Direction::Left;
    }
    return d;
}

// functional core
constexpr EvaluationResult evaluateDirectionChange(Direction current, Direction requested) {
    if (requested == opposite(current)) {
        return {false, SoundEffect::InvalidInput};
    }

    return {true, SoundEffect::None};
}

// imperative shell
int main() {
    Direction snake_direction = Direction::Right;

    while (true) {
        Direction input = readUserInput();  // effectful

        auto result = evaluateDirectionChange(snake_direction, input); // calling core

        if (result.sound_effect != SoundEffect::None) {
            playSound(result.sound_effect);  // effectful
        }

        if (result.direction_changed) {
            snake_direction = input;  // effectful
        }
    }
}

The evaluateDirectionChange function is the functional core—it's pure, encoding the business rule about the game's behavior on direction changes. The main function is the imperative shell—it calls the core, interprets the result, and performs side effects like reading user input, playing sound, or mutating the game state.

Starting Small Works Well

The functional core–imperative shell pattern allows you to clearly distinguish between the imperative and the pure worlds, while having them bridged via simple function calls.

Yes, this is a fundamental shift in how to deal with side effects. But this approach doesn’t invalidate your existing C++ design. Instead of starting from scratch, it's about shifting where effectful behavior takes place. And, it's not about all or nothing, in practice you can start small. The pattern works also for a subset of your business logic. Take a piece of code and split out the side effects. Already with the first step you gain better testability and reasoning for the resulting pure world code as described in the previous post. Then incrementally push more side effects to the edges.

Where This Leads Next

The functional core–imperative shell pattern works well for decoupling business logic from side effects, that problem is solved.

But as applications grow, a new problem appears: the shell starts accumulating unrelated responsibilities. Even in a simple snake game, this escalates quickly: handling user input, playing sound, managing the game state, and performing screen IO all end up in the same place.

In my next post, I will show how to refine this design further so these responsibilities can be separated cleanly as well.

Part of the funkyposts blog — blogging to bridge traditional C++ and functional programming by exploring how functional patterns and architectural ideas can be applied in modern C++. Created with AI assistance for brainstorming and improving formulation. Original and canonical source: https://github.com/mahush/funkyposts (v03)

Bridging Object-Oriented and Functional Thinking in Modern C++

Matti | funkyposts — Tue, 24 Mar 2026 22:15:00 +0000

Why functional programming got me — and the design changes that followed

C++ development is still heavily shaped by object-oriented thinking. In real-world projects, this can create friction—especially around testing and tight coupling. At the same time, modern C++ has evolved into a multi-paradigm language with increasingly strong support for functional programming. But having the tools doesn’t automatically change how we design systems. In this post, I will explore what actually changes when you start combining object-oriented and functional thinking in C++, based on the experiences that led me here.

My Early Days

In the first years of my career I aimed to master OOP as provided by C++98. What I knew about programming at that time brought me to the conclusion that writing high quality code is just a matter of being fluent in the language, the object-oriented paradigm and the design patterns around it. So, I was practicing, and as the years passed and my ability to write idiomatic object-oriented code improved I began to see its limits.

To better understand my journey here, let me share another complementary learning path of mine that is about testing. The first embedded projects I joined didn’t have any automated tests. Instead, testing was done manually by using the device, observing its behavior and pressing its buttons. We developers did this ourselves to see if our changes worked and a dedicated test department did so all day to “ensure” the device generally behaves as expected. In a later embedded project two colleagues were practicing unit testing for their production code. Given how many regressions we had experienced and how much effort it took to fix them in coordination with the test department, I realized the potential of automated tests. So, I started writing unit tests myself. At that time, the OOP patterns I was applying became limiting.

Where I Struggle with OOP

When diving into unit testing, an essential learning was: If you want to unit test your code, you actually must write your code to be unit-testable. In short, you must be able to execute smaller parts of your code in isolation. That is applying the “separation of concerns” principle, which provides the units for testing. And to actually run modules independently, dependency injection comes into play. This means if one module depends on another, it is passed in, normally as a constructor argument. In a unit test where a single module should run in isolation, all dependent modules need to be mocked. Instead of real dependencies, the test passes its mocks as constructor arguments.

No testing without mocking: Technically that mocking approach works well; unit testing is enabled. But actually it comes at a high price. The mocks need to be written and maintained, which increases test-specific code and in turn leads to higher test complexity. And we should not neglect this, as only if all the mocks are implemented correctly, the test is helpful.

Interfaces create tight coupling between alternative implementations: Mocks must implement the same interface as the real components they replace. These interfaces often contain several interdependent function signatures with non-trivial pre- and post-conditions. Any change affects all implementations and thus also all mocks, which increases maintenance effort. With dependency injection and many mocks, this interface-level coupling becomes especially visible and expensive. So, we often trade testability for flexibility here, which can be a poor deal.

State encapsulated within a class is hard to modify by a test: In traditional OOP, private mutable state is fully hidden, so tests cannot set it up directly. A test that needs the object in a specific internal configuration must drive the state there indirectly through the public interface, which often requires multiple method calls, complex sequences, and mocks. This indirect setup adds unnecessary complexity and makes tests more brittle.

Kudos to Eric Elliott who wrote the blog post Mocking is Code Smell that helped me gain a better understanding of these issues and how functional programming allows us to do better. This really got me. My interest in functional programming was born.

Looking at OOP from an FP perspective also made another long-standing issue clear: inheritance.

Inheritance creates tight coupling within the hierarchy: Once a class hierarchy is established, the base class interface becomes almost impossible to change without impacting every derived class. Even small adjustments propagate through the hierarchy, making class hierarchies rigid and expensive to evolve.

So, these were my pain points, and I was primed to find solutions in functional programming and I did.

What Functional Thinking Unlocks

The key idea is to start thinking in terms of pure functions alongside classes. A pure function is as simple as it gets: it takes input and returns output, with no hidden state and no implicit dependencies. Using pure functions as building blocks unlocks an additional solution space. For example, the issues described above evolve as follows:

Testability improves: This makes testing straightforward, you call the function with test data and check the result. No hidden state means no complicated setup, and no implicit dependencies mean you don’t need objects standing in for other objects. You may need to supply a function as an argument when testing. But this “mock” is just a single, stateless function, not an entire class with multiple methods and internal state. The complexity drops dramatically. So the takeaway is this: when you structure your logic as pure functions, the heavy mocking simply disappears.

Coupling decreases: Of course, class hierarchy coupling also goes away with FP, functionality still builds on top of other functionality, but when this essentially means composing pure functions, all dependencies are only at the function signature level which again reduces complexity.

In other words, when you compose your business logic out of pure functions, the design becomes cleaner, improving both testability and maintainability. Don't get me wrong, this is not about replacing OOP with FP, it's about complementing where appropriate.

If This Resonates

Sure thing, learning a new programming paradigm takes sustained effort, and how much depends on your learning path. If you’re coming from an OOP-heavy, C++-style background like I did, I might speak your language well enough to make functional programming feel more approachable. My original motivation wasn’t to blog about functional programming. I simply wanted to figure out how to apply its ideas effectively in real-world C++ code. After exploring this for a while and finding techniques that work for me, it feels natural to share and discuss them. The funkyposts blog is my attempt to build a bridge between traditional C++ and functional programming by illustrating practical FP patterns in modern C++. Hopefully this helps other C++ developers go more functional while inviting constructive feedback on my own understanding.

Dive deeper

As said, I advocate for implementing the business logic, the heart of an application in a functional style, while utilizing traditional C++ for everything else. The subsequent posts in this series will show how to structure an application accordingly.

Interfacing Pure Functions with Our Impure World — How to structure applications using the functional core–imperative shell architecture
More posts in this series coming soon