DEV Community: Matti | funkyposts

Mastering State in Modern C++: Making It Protected

Matti | funkyposts — Thu, 25 Jun 2026 06:12:06 +0000

Mastering State in Modern C++: Making It Protected

Explicit state with protected evolution

Earlier, we made state explicit by passing it through pure functions. This naturally allows state and functions to be composed flexibly. Any function can consume or evolve any combination of state, and any state can participate in multiple functions.

But some state must be adjusted carefully. As systems grow, the logic that evolves a state often becomes scattered across the codebase. Different pieces of code start modifying the same state, and those modifications become implicitly dependent on one another. Understanding or changing the evolution of that state then requires reasoning across many locations at once.

A snake body is a simple domain-level example. It must remain a connected chain. Movement must preserve that structure, and dead snakes must not move. If any code can arbitrarily modify body segments, those rules become hard to keep consistent.

The usual object-oriented solution would be to evolve that state through class methods. But we still want state evolution to remain explicit.

How can we protect state evolution without hiding it?

Protecting State Modules

As in a previous post, we group state together with the pure functions that operate on it. But this time the focus is different. Previously, the module localized the meaning of state. Now it localizes the evolution of state.

I call this a Protecting State Module. Its purpose is to protect state evolution by preserving validity over time. That includes what must always be true about the state, and how the state may change. So it becomes useful when state has invariants or restricted transitions.

Because a Protecting State Module owns only state evolution and not state meaning, other functions may depend on the state and build their logic on top of it. The restriction is not about reading, but only about directly modifying it.

Here is the pattern in a visual nutshell:

An Example: Protecting Snakes

Let’s return to the funkysnakes project and look at a snake itself.

The game stores snakes as part of its domain model. This makes the concept available throughout the game. To ensure that snake evolution remains valid, snakes are implemented as a Protecting State Module, here called snake_model.

The module defines the Snake type together with the query functions head, tail and alive to enable read access to the current snake state. This allows any part of the game logic to depend on the concept of a snake in a read-only way.

namespace snake::snake_model {

class Snake {
 private:
  Point head_;
  std::vector<Point> tail_;
  bool alive_;

  friend const Point& head(const Snake&);
  friend const std::vector<Point>& tail(const Snake&);
  friend bool alive(const Snake&);

  friend Snake initial(Point, Direction, int);
  friend Snake move(Snake, Direction, const Board&);
  friend Snake kill(Snake);
};

const Point& head(const Snake& s);
const std::vector<Point>& tail(const Snake& s);
bool alive(const Snake& s);

}

In addition, the module provides the state-evolving functions initial, move and kill. So, whenever a snake needs to be modified, these functions are utilized.

namespace snake::snake_model {

Snake initial(Point head, Direction direction, int length);
Snake move(Snake snake, Direction direction, const Board& board);
Snake kill(Snake snake);

}

As usual, the shell stores the game state, which includes the snakes.

namespace shell {

struct GameState {
    ...
    snake_model::Snake snake;
    Direction direction;
    Board board;
};

class GameEngineActor : public Actor<GameEngineActor> {
    ...
    GameState state_;
};
}

Here a piece of logic that is not part of the module but still builds on top of the snake state.

bool snakeBitesItself(const snake_model::Snake& snake);

In the context of the game loop, the shell triggers evolution of its game state, but the rules for changing the snake are defined by the module. Still other functions like snakeBitesItself can depend on snakes.

state_.snake = snake_model::move(state_.snake, state_.direction, state_.board);
if (snakeBitesItself(state_.snake)) {
    state_.snake = snake_model::kill(state_.snake);
}

Deriving the Module Pattern

Generalizing the snake example shows the underlying pattern.

namespace protecting_state_module {

class State {
 private:
  int value_;

  friend int value(const State&);
  friend State evolve(State, Input);
};

// query functions
int value(const State& s);

// evolving functions
State evolve(State state, Input input);

}

The module defines a state type together with two different types of functions:

Query Functions simply provide access to state details. As Protecting State Module share the meaning of its state with the outer world, query functions enable any other function to build on top of its state in a read-only way. This keeps up the flexibility we initially gained with making the state explicit.

Evolving Functions allow modification of the state, but only as encoded by these functions. Anyone that holds the state may invoke them. So the flexibility of who may evolve state remains, but the how is encapsulated in the module. This way state evolution is protected.

The protection is enforced through language-level access control using private data members and a set of friend functions. This matters because meaningful state tends to attract direct modification: once other code can see the representation, it is tempting to adjust it in place. Private data members prevent callers from bypassing the module’s rules.

The tradeoff is that tests can no longer freely construct or modify arbitrary internal states. Instead, they interact with the module through its public state-evolving operations and state queries. Tests apply state changes and verify the resulting behavior through the module’s observable outputs.

What Protection Changes

A Protecting State Module separates code that may evolve state from code that may not.

By forcing all state-evolving operations into the module, it localizes state evolution. This means that the rules for how state may change are implemented in one place. To understand how state can evolve, you no longer have to track down every function that relates to it. The rules are no longer scattered across the codebase.

Looking at this through the dependency lens clarifies the effect of the module boundary: outside the module, a state-modifying dependency no longer implicitly means a dependency on how that state evolves. Instead, state-modifying dependencies are limited to requesting state changes through the module’s interface. This leads to an important distinction:

Dependencies on triggering state changes may still be spread throughout the system. Different parts may decide that a snake moves or gets killed. Those are dependencies on the module’s state-evolution interface.
In contrast, dependencies on the evolution logic itself are localized to the module. The rules that define what moving or killing a snake actually means are concentrated in the module. As a result, reasoning about state evolution becomes much simpler. Instead of considering the entire system, you only need to consider a single module.

Protection is a direct consequence of this localization. Because dependencies on the evolution logic are contained within the module, outside code cannot arbitrarily modify the state. The state is protected because no dependency on its evolution logic can exist outside the module.

Note that there are different aspects to protect. Some modules primarily protect invariants that must always hold. Others primarily define valid transitions between states. Many do both, like the snake example. The snake_model defines how a snake may change (move or kill), while also ensuring that the resulting snake remains valid (keeping its body segments connected).

Even though state evolution is localized, the state itself remains part of the broader system. State changes are protected, but state meaning is not. Therefore read-only dependencies remain meaningful.

The key takeaway is this: State remains explicit, but the responsibility for evolving it is localized. The state concept may belong to the broader system, while its valid evolution is owned by the module.

This is how to Master State

Mastering state begins with making state explicit. State becomes visible in the design and flows through the system as data. Functions no longer implicitly depend on hidden mutable state, and state evolution becomes an explicit part of the program structure.

Once state is explicit, a new set of design questions appears:

Who should understand the meaning of state?
Who should define how state may evolve?

One answer is an Encapsulating State Module. It localizes state meaning. The state remains explicit, but only the module itself interprets it.

Another answer is a Protecting State Module. It localizes state evolution. The state remains explicit, but only the module itself defines how it may change.

These concerns are independent. A module may own the meaning of state, the evolution of state, both, or neither.

This is possible because both patterns build on the same underlying mechanism: grouping state with pure functions operating on that state into a module. Whether this results in encapsulation, protection, or both depends on how the state is shared and on the role those functions play. Encapsulating and Protecting State Modules are therefore not competing module types. They are complementary ways of assigning ownership within the same module.

The choice is therefore selective. Such modules become useful only when either the meaning of state or the valid evolution of state needs an owner. Otherwise, state can simply remain explicit.

Ultimately, making state explicit is the foundation. From there, the design challenge becomes deciding whether localizing state meaning or state evolution is worth the additional boundary.

This post is created with AI assistance for brainstorming and improving formulation. Original and canonical source: https://github.com/mahush/funkyposts (v01)

Mastering State in Modern C++: Making It Encapsulated

Matti | funkyposts — Thu, 28 May 2026 07:52:30 +0000

Explicit state with encapsulated meaning

Previously, we made state explicit by assigning state evolution to the core and state persistence and mutation to the shell. This made state visible at the highest level, and changing it required explicit passing between shell and core.

So far, we looked at state that had broader meaning in the system. The shell knew about snakes and food, and passed them around intentionally. But some state is more localized: a parser may need to remember where it is in an input stream, or a cache may need to remember previous lookups.

Handling such details as if they had broader significance would promote module implementation details to first-class concepts outside the module. Worse, unrelated logic could start depending on these details unintentionally. The system would still be explicit, but internal implementation details would start leaking into the surrounding code.

In object-oriented C++, we would usually solve this by putting the state behind a class interface. But if we want to keep the functional mechanics from the previous posts, the question becomes more specific:

How do we encapsulate internal implementation details without going back to objects whose behavior depends on hidden mutable state?

This post shows how pure functions operating on shared module state can form a coherent stateful module — one that keeps state evolution explicit while encapsulating module state.

Encapsulating State Modules

An Encapsulating State Module groups a state definition together with pure functions that interpret and use that state. Its state exists solely for the module’s own purposes. No code other than the module itself has a reason to understand what that state means.

As before, the shell still persists and updates state by replacing the current value with the value returned from a pure function. The difference is not in how the state evolves, but in how it is treated. The shell still stores and threads the state through the system, but only the module itself interprets what that state means.

Treating the state this way creates the module’s encapsulation boundary. The shell passes the state to the module because its type identifies the owning module, not because the shell understands what the state represents. Code outside the module may store and pass the state, but should not depend on its internal structure.

An Example: An Encapsulated Filter

Let’s dive into some code from my funkysnakes project and see the idea in action.

Snakes are controlled via the arrow keys. But the game loop and key events are asynchronous. At the beginning of each game loop tick, each snake's movement direction is updated based on new key events received since the previous tick. This direction-update logic is implemented in the direction_command_filter module. As the name suggests the logic is implemented by filtering key-press events.

Unsurprisingly, this module maintains its own state: a queue of direction commands per player. This state exists only to implement the filtering logic. Outside the filter module, the queue itself has no meaningful role.

namespace direction_command_filter {
struct State {
    using PerPlayerDirectionQueue = std::map<PlayerId, std::deque<Direction>>;
    PerPlayerDirectionQueue queues;
};
}

The direction_command_filter module's interface provides two functions. tryAdd, which feeds direction commands into the filter, and tryConsumeNext, which retrieves the next direction that passed the filter. Both functions may evolve the module state:

namespace direction_command_filter {

State tryAdd(State state, const PerPlayerSnakes& snakes, const DirectionCommand& cmd);

std::tuple<State, PerPlayerDirection> tryConsumeNext(State state);
}

The regular domain state, PerPlayerSnakes, is stored alongside the module-local state, direction_command_filter::State:

namespace shell {
struct GameState {
    ...
    PerPlayerSnakes snakes;
    direction_command_filter::State direction_command_filter_state;
};

class GameEngineActor : public Actor<GameEngineActor> {
    ...
    GameState state_;
};
}

The GameEngineActor then threads the module state through tryAdd and tryConsumeNext:

state_.direction_command_filter_state = direction_command_filter::tryAdd(state_.direction_command_filter_state, state_.snakes, new_command);

auto [new_state, direction] =
direction_command_filter::tryConsumeNext(state_.direction_command_filter_state);
state_.direction_command_filter_state = new_state;

Deriving the Module Pattern

This example is concrete, but zooming out reveals the underlying pattern:

namespace module {

struct State{ ... };

State operation(State state, Input input);
}

The module defines a state type and a set of pure operations over that state. Each operation receives the current state and returns the updated state.

The namespace forms the module boundary. It groups the state type together with the operations that interpret and evolve it. In that sense, module is self-contained: its behavior can be tested by constructing a State, calling its pure functions, and checking the returned state.

The namespace also gives the operations a visible scope, much like a class name would for member functions. Client code calls module::operation and stores module::State, so the module boundary remains visible at the call site. This also means the state type can simply be called State: The required meaning comes from the namespace it belongs to.

Here the shell side at a glance:

namespace shell {

module::State module_state;

module_state = module::operation(module_state, input);
}

The shell persists the current state between calls and threads it through the module operations. It stores the state, passes it to the module, and replaces it with the returned value. The state remains visible, but it is treated differently: surrounding code only carries it through the system but does not interpret it.

What Encapsulation Changes

Functional design allows broad composition over shared state: pure functions can combine and transform whatever data they need. Encapsulating State Modules introduce a boundary into that otherwise flexible model. Their state remains explicit and still evolves through pure functions, but it stays localized to the module that owns the corresponding implementation logic instead of becoming generally shared data.

When looking at this pattern through the dependency lens, we can see that outside code should depend on the module boundary, not on the module implementation. The shell may store module::State and call module::operation, and other operations may receive or pass that state as needed. But none of that code should read fields from module::State or base decisions on its internal structure. Once surrounding code starts depending on those details, the module’s internals leak into the system. The pattern is meant to prevent exactly that: dependencies on module internals.

In the snake example, direction_command_filter::State is module-local state, while PerPlayerSnakes is passed in as an input. The filter module owns its queue state, but can still consume other state when needed. This is an important distinction: an Encapsulating State Module is not isolated from the rest of the system. It depends on the meaning of other state to perform its work, but it does not expose the meaning of its own state. This keeps the useful flexibility of sharing state across pure functions, while keeping the filter’s queue state localized to the module.

For this kind of module-internal state, conceptual encapsulation is often sufficient. The state is clearly identified as belonging to a specific module, and has no broader meaning in surrounding code. That makes accidental external use less likely than with generally shared state, where many parts of the system may naturally want to inspect or modify the data. Stronger language-enforced encapsulation is also possible, but it becomes more relevant when state evolution itself needs protection.

The conceptual encapsulation used here also allows more flexible testing. Tests can still treat the module as a public API and verify behavior through its operations. But when useful, they can also construct relevant states directly, pass them through pure functions, and inspect the returned results without driving an object through long sequences of mutating method calls.

The key idea is this: state evolution remains explicit, but state interpretation stays localized. From the shell’s perspective, module state is treated like a black box: the shell stores it and threads it through module functions, but never peeks inside. As a result, the state remains local to the module that interprets it, and outside code does not depend on how the state is represented or what it means internally. The state is visible as a value, but encapsulated as a module-owned concept.

State is not mastered yet

This post showed how state can remain explicit without becoming a shared concept throughout the system.

But explicit state and encapsulated meaning are not the full story yet. Sometimes state should be adjusted carefully.

That is the next step: keeping state evolution explicit while introducing protection around how that state may evolve.

This post is created with AI assistance for brainstorming and improving formulation. Original and canonical source: https://github.com/mahush/funkyposts (v02)

Mastering State in Modern C++: Making It Explicit

Matti | funkyposts — Wed, 06 May 2026 07:30:00 +0000

Passing state as data in the functional core–imperative shell

In object-oriented systems, logic often depends on state hidden inside objects. At a call site, you typically see only a function and its explicit inputs, not the internal state that may also influence its behavior.

The functional core – imperative shell pattern aims to make such dependencies explicit by separating logic from effects. State is one such effect. But what does that separation mean in practice? How can logic still determine what the next state should be?

Without a clear answer, state easily becomes an implicit dependency again—undermining the very goal of the whole design.

How State Flows Through Core and Shell

The functional core – imperative shell pattern separates logic from side effects. For state, this means that although the logic in the core drives changes, it does not persist or mutate state.

This is resolved by letting state live in the shell, while the core receives it as input and returns updates. So, state evolution follows a clear pattern:

persisted and routed by the shell: the shell holds the current state and passes it as data into a core function
driven by the core: the core function computes and returns an updated state
mutated by the shell: the shell applies the returned state

This way, the logic still determines how state evolves—but without persisting or mutating it.

In consequence, there is a clear responsibility split: the shell owns persistence, routing, and mutation, but not meaning. It may store state, pass selected state into core functions, and replace stored state with returned values. However, it does not interpret the internal structure of that state. The core owns that meaning and therefore evolves state through its logic.

Let’s dive into an example, to see how state flows between shell and core.

Seeing It in Code

Here is a concrete example from my funkysnakes github project that illustrates the pattern clearly. The project implements the actor-based functional core–imperative shell architecture introduced in an earlier post.

In this example, the snakes are part of the game state, and moving them means evolving that state.

The GameEngineActor, as shell, holds the GameState struct that aggregates the relevant sub-states:

// Shell: where state is persisted
class GameEngineActor : public Actor<GameEngine> {
  ...

  struct GameState {
    PerPlayerSnakes snakes;
    FoodItems food_items;
    Board board;
  };
  GameState state_;
};

The core provides the pure function moveSnakes depending on the sub-states snakes, board, and food_items. It advances the snakes by one step, returning updated snakes while board and food_items are only read. Another pure function replenishFood follows the same pattern.

// Core: where state evolution is driven
PerPlayerSnakes moveSnakes(PerPlayerSnakes snakes, 
                           const Board& board, 
                           const FoodItems& food_items);

FoodItems replenishFood(FoodItems food_items,
                        const Board& board,
                        const PerPlayerSnakes& snakes);

Finally, moveSnakes and replenishFood are called by the shell within the game loop of the GameEngineActor.

// Shell: where state is mutated
state_.snakes = moveSnakes(state_.snakes, 
                           state_.board, 
                           state_.food_items);

state_.food_items = replenishFood(state_.food_items, 
                                  state_.board, 
                                  state_.snakes);

This example maps to the functional core–imperative shell design:

the core is the pure functions moveSnakes, replenishFood
the shell is the GameEngineActor, which holds and mutates the state
both connect at the function call, where the core’s result is applied to the state

One key detail is how state is perceived differently. In the shell, GameState persists across calls and is mutated over time—this is what makes it state. In the core, however, there is no notion of state—only data passed in and returned. This is exactly what allows pure functions to drive state changes without mutating state themselves.

The example also reveals a subtle boundary: selecting sub-states is not interpreting them; it is routing. The shell may pick snakes, board, and food_items from GameState and pass them to moveSnakes or replenishFood, but the interpretation of those values remains in the core.

What This Design Gives You

Looking at the following benefits through the lens of dependencies reveals why they arise:

One key aspect is transparency. All state appears at the top level, making it obvious which state exists. State changes are explicit and easy to follow, rather than scattered deep inside objects as is often the case in nested OOP designs. What makes this possible is that state dependencies are no longer hidden, but explicit.

There is also high flexibility in which state can be processed by which function. Here the snakes sub-state is updated by moveSnakes, while depending on the board and the currently existing food_items. The same state can also be passed into replenishFood, where food_items are updated while depending on board and snakes. So you are free in two directions: each operation can choose the state it depends on or evolves, and generally logic can be sliced into functions as needed because state can always be passed along. New operations can even be added as pure functions over existing state, without changing existing operations. New dependencies may be introduced, but they remain explicit because they are expressed as function parameters.

And another great benefit of this design is that it improves testability significantly. As pointed out in the intro post, testing stateful code is often complex. To test a specific behavior, you first need to get your software into the right state. This means using the regular API, test-specific APIs, or mocks. This changes when logic no longer depends on hidden internal state, but only on explicit input. With these dependencies exposed, you can simply pass in whatever state you need, making testing straightforward.

In conclusion, all of these benefits stem from the same shift: state dependencies become explicit instead of hidden.

Where This Reaches Its Limits

So far, we looked at state that can be passed freely through pure functions. Making state explicit gives us transparency, flexibility, and testability. But explicit state alone leaves important ownership questions open.

Some state is an implementation detail—parser state, cache state, or other internals. Making such state explicit should not mean exposing its meaning throughout the surrounding system.

And some state should not be modified freely. Making state explicit should not mean that its evolution can be defined anywhere. State often has invariants or valid transitions that should be preserved consistently.

These concerns lead to additional ways of structuring explicit state. In the next post, we will look at Encapsulating State Modules: keeping state explicit while localizing its meaning. After that, we will look at Protecting State Modules: keeping state explicit while localizing its evolution.

This post is 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 — Wed, 29 Apr 2026 07:15:45 +0000

How dependencies make C++ systems hard to test and evolve—and why functional thinking changes it

Fighting complexity is crucial if you want to succeed in software development. In many real-world C++ projects, however, systems tend to evolve in the opposite direction. Components become tightly coupled, so changes ripple through large parts of the system. State is scattered, reducing transparency about how it evolves over time. Behavior emerges from many interacting parts, making it hard to reason about individual pieces in isolation.

This also shows up in testing: a significant amount of boilerplate and indirection is needed just to enable it. Establishing specific system states requires substantial setup, and maintaining tests becomes costly, as even small production changes force updates across large parts of the test code.

The result is a system that is hard to get right—and once it works, it feels rigid and difficult to evolve.

Where OOP Leads to Complexity

The underlying problems unfold nicely when jumping into the details from the testing point of view. So, let's focus on unit-testable code, that is code structured in smaller parts that can be executed in isolation. To get there we apply 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. So, instead of real dependencies, the test passes its mocks as constructor arguments.

This reveals the first issue: 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.

Mocks must implement the same interface as the real components they replace, which leads to another problem: Interfaces create tight coupling between alternative implementations. Often these interfaces 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.

But the challenges don’t stop at interfaces. Once state comes into play, things get even more complicated: 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 complexity and makes tests more brittle.

Actually, state handling in a traditional OOP manner has another problematic dimension: Generally state is cluttered across the object graph. This introduces state dependencies that are hard to see. The more stateful objects exist, the harder it gets to reason about how state evolves in the system. Of course, this compounds the state-related test complexity mentioned earlier.

Interestingly, testing just makes these problems visible—but they exist in the design itself. E.g. the tight coupling of implementations sharing an interface can be described more generally as: Inheritance creates tight coupling within the hierarchy. So, once a class hierarchy is established, the base class interface becomes almost impossible to change without impacting every derived class. This gets worse the deeper the hierarchy is. Even small adjustments propagate through, making class hierarchies inflexible and expensive to modify.

Let's step back and draw conclusions. All these problems create a lot of complexity. This way they cause the pain described in the beginning. But there is more to understand here: The root cause is dependency—complexity emerges as different kinds of dependencies accumulate:

components dependent on each other based on injection can only be executed in isolation by introducing mocks
the broader an interface, the more complex the dependency between components sharing it
inheritance causes dependencies between classes within hierarchies
hidden, distributed, and evolving state creates implicit dependencies across the system

Every issue we looked at comes down to this: dependencies force parts of the system to change together, to be set up together, and to be understood together. As they reinforce each other, complexity grows increasingly fast.

What Functional Thinking Unlocks

So, I started questioning the design ideas I was following for years and searched for different ways of structuring my code to better manage these dependencies. The blog post Mocking is Code Smell helped me see this more clearly. It also pushed me to explore functional ideas that turned out to be particularly useful. Put simply, functional programming offers techniques that can complement a traditional C++ toolbox.

These techniques work because they change how we design systems—and with that, which dependencies emerge. To get an idea of what changes, consider pure functions as building blocks for your logic:

Pure functions receive all dependencies explicitly as input, instead of relying on injected objects. This eliminates implicit dependencies and significantly reduces the need for mocking.
In a world of pure functions, there is no hidden state, so dependencies on state are always explicit and visible.
Function interfaces are typically narrower than class interfaces, which keeps dependencies simpler.
There is no inheritance hierarchy, removing an entire class of dependencies

In conclusion, when you compose your business logic out of pure functions, dependencies become explicit, fewer, and simpler. This directly mitigates complexity.
The design becomes clearer, and as a result, reasoning, testing, and maintenance improve.

Just to be explicit, I am not saying functional programming is going to solve all problems, nor that it’s applicable in C++ without limits. I am saying there are aspects that are highly valuable when designing C++ systems. So, I advocate for complementing OOP with FP where appropriate.

If This Resonates

Adopting a different way of structuring code takes 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 further clarify these techniques and design choices.

My original motivation wasn’t to write about system design or functional programming. I simply wanted to figure out how to apply these ideas effectively in real-world C++ code. After exploring this for a while and finding techniques that work, it feels natural to share and discuss them.

The funkyposts blog is meant to build a bridge between traditional C++ and functional programming by illustrating practical FP patterns in modern C++. The goal is to provide concrete ways to improve how systems are structured—while staying grounded in real-world constraints. I also welcome feedback and different perspectives to further refine these ideas.

Dive deeper

The next step is to leverage these insights in practice—improving existing designs without rewriting everything. The subsequent posts in this series show how.

Handling Side Effects in Modern C++: Interfacing Pure Functions with Our Imperative World — Using the functional core–imperative shell pattern to mitigate dependencies
When One Shell Isn’t Enough: Scaling the Functional Core–Imperative Shell Pattern with Actors in C++ — How to structure growing C++ systems into actor-driven core–shell pairs that isolate dependencies
Mastering State in Modern C++: Making It Explicit — Making state flow explicit in the functional core–imperative shell pattern
Mastering State in Modern C++: Making It Encapsulated — Localizing module-internal state without hidden mutation or domain model pollution
More posts in this series coming soon

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 (v07)

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 actor-driven core–shell pairs that isolate dependencies

The previous post showed how the functional core–imperative shell pattern decouples the business logic from side effect handling by centralizing all side effects in the shell.

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: more and more unrelated concerns end up sharing the same context. As a consequence, they can accidentally influence each other, or at least make it harder to see which dependencies actually exist. The shell has to be sorted out again and again, making the code harder to reason about and maintain.

This raises the crucial question: how do we scale the functional core–imperative shell pattern without tying together parts that shouldn't influence each other?

The Design Idea: Actors as Shell

In order to keep things clean, we need to decouple unrelated shell concerns. Thus, a single shell isn’t enough—we need multiple ones, each handling an independent, non-overlapping subset of side effects.

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. Thus, the system is structured into multiple core–shell pairs, each forming its own isolated unit around a specific concern. Each unit owns its behavior end-to-end—from handling input effects in its shell, through business logic in the core, to producing output effects via the shell. This is not just splitting the shell, but partitioning the system into smaller, self-contained slices that evolve independently.

One concrete option to put this idea into practice is using the actor model. Actors are inherently separated from each other, so they naturally provide the needed isolation. The approach 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 communicate through messages.

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.

Building on this, 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.

flowchart TD

subgraph InputActor["Input Actor (Shell)"]
    InputCore["Functional Core"]
end

subgraph GameEngineActor["Game Engine Actor (Shell)"]
    GameCore["Functional Core"]
end

InputActor -->|DirectionMsg| GameEngineActor

Why this scales

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

Separation of Concerns: Clear Responsibilities and Boundaries
The input handling and game logic are completely decoupled. Each actor focuses on a narrow, well-defined concern. 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: Isolation
Complexity is distributed across multiple isolated shells. Each shell only handles its own side effects, so unrelated parts no longer share the same context and cannot accidentally interfere with each other. The GameEngineActor cannot publish direction messages, and the InputActor cannot access or modify the game state or the game loop timer. Each part is isolated and can be understood without needing to consider the behavior of the others.
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 actors do not share mutable state and each actor mutates its state sequentially. 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.

Applying the dependency lens from the intro post gives another perspective on why this design scales: it’s not just the separation itself, but how it constrains dependencies. By isolating actors from each other, all cross-actor dependencies are ruled out upfront except those explicitly expressed through message passing. Without shared state or a shared execution context, message passing is the only way for parts of the system to influence each other. As a result, the system becomes easier to reason about, test, and evolve because fewer parts are able to influence each other.

Key Advantage: Bridging by Design

There is another very important benefit that goes beyond modularity: The actor-based functional core–imperative shell design is able to bridge naturally object-oriented and functional code via inter-actor communication.

This is powerful in practice because the actor boundary lets both styles coexist without forcing the whole system into one paradigm. 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 that choice.

Where we arrived at

The functional core – imperative shell pattern scales by partitioning the system into multiple core–shell pairs. This isolates unrelated concerns like input handling and game state evolution, effectively preventing unintended dependencies between them.

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

However, when that additional structure is justified, you gain valuable isolation that simplifies reasoning and maintenance.

On top of that, it enables clean bridging between traditional object-oriented design and a functional approach. 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 how state is represented and passed. In the next post, I will take a closer look at state management and how to handle it effectively.

Handling Side Effects in Modern C++: Designing Systems Around Pure Functions

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

Using the functional core–imperative shell pattern to mitigate dependencies

In the previous post, we saw why structuring business logic without side effects—using pure functions—effectively mitigates dependencies and makes code easier to reason about and test.

But applying this idea in a real system isn't straightforward: Although you want your functions without side effects, the application you are building still must perform IO and maintain state to be useful.

This leads to a practical design question: how do we structure systems so that side effects are decoupled from the business logic?

Decoupling Logic and Side Effects

The key idea is clear separation at the system level. So, instead of mixing business logic and side effects in the same place, one part of the system focuses on logic, while another is dedicated to side effect handling.

In this setup the logic still determines which effects should happen, but without performing them directly. Instead, it describes what needs to happen, and the surrounding code interprets and performs the effects.

If this reminds you of the command pattern, that’s not a coincidence—but here the idea is used to organize the entire system. And this is exactly the separation that structuring logic as pure functions naturally leads to.

For example, a pure function decides to create a log message, so it returns a string and the caller interacts with the outside world by printing it to stderr.

The Functional Core–Imperative Shell Pattern

This simple structure is called functional core–imperative shell: it splits an application into a functional core and an imperative shell.

The functional core, is where the business logic is encoded in pure functions. You can wire these functions freely. This lets you build various layers of abstraction and organize the business logic cleanly.

The remaining part forms the imperative shell that calls the core and performs effects. For a C++ developer this is familiar terrain: using the standard library to write to stderr, mutating private members, using protocol stacks to communicate with other systems, or managing timers. In addition, the shell is responsible for managing the application’s execution environment, such as setting up concurrency. There is only one constraint: don’t implement business logic here.

One important design aspect is the direction of dependencies: the shell depends on the core, but the core is independent of the shell. This enforces the clean separation as it prevents effects like state, IO, or other external concerns from leaking into the business logic and keeps the core self-contained.

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.

// functional core
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;
}


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

    return {true, SoundEffect::None};
}

These functions and their input and output types form the functional core. Here the business logic about the game's behavior on direction changes is encoded.

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

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

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

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

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

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.

Recap - What has changed

The separation into core and shell shifts how business logic is structured and how it interacts with the rest of the system. But let's state it more concretely:

the business logic no longer performs effects directly but only decides what should happen
side effect handling (IO, state mutation) is no longer distributed across the business logic but centralized outside of it
state is no more hidden and implicitly mutated but visible at the top level and explicitly passed into the core and returned

Together, these changes introduce an explicit interface between the pure business logic and the effectful parts of the system at the cost of introducing additional types to describe those effects.

Looking at it through the lens of dependencies from the previous post, the situation improves as follows:

the business logic has no dependencies on external systems
fewer places in the system depend on IO or state mutation, and these dependencies are localized instead of spread across the system
state dependencies are explicit: the business logic depends only on input data passed in and returned, not on internal mutable state

As a consequence, reasoning about the business logic becomes significantly easier, and testing follows naturally: you call the function with input values and verify the result—without heavy mocking, dependency injection, or complex setup. This is exactly the improvement we were aiming for in the previous post.

In addition, effect handling becomes easier to understand and control, as it is no longer spread across the logic but centralized in one place.

So, the main achievement of functional core–imperative shell is removing hidden dependencies from the business logic and localizing the remaining ones.

Starting Small Works Well

Although this is a fundamental shift in how to deal with side effects, it doesn’t require an all-or-nothing redesign. The pattern works for a subset of your business logic, so you can apply it locally, one part of the system at a time: start by moving effectful behavior out of a single piece of business logic while leaving the surrounding structure in place. From there, you can incrementally restructure more of the system step by step.

Where This Leads Next

All the side effect handling is now centralized in the shell. As the application grows this accumulates complexity there. Even in a simple snake game, this escalates quickly: handling user input, playing sound, managing the game state, and performing screen IO.

In my next post, I will show how to refine this design further to better organize the application to address scaling.

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

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

Re-published with major changes

This post has been significantly revised. Read the updated version here.

This post previously explored combining object-oriented and functional programming in C++. However, the perspective has shifted—especially regarding how dependencies impact system design and testability.

To avoid confusion, please refer to the updated version above, which reflects the current direction of this series.