kp-actor-pattern

One-line summary

Hide mutable state inside one coroutine; let the outside world send it messages on a channel. The coroutine processes one message at a time, so the state is implicitly single-threaded — no locks needed.

When to use this skill

• Coordinating concurrent updates to a small piece of state (counters, caches, in-memory aggregates, session state).
• Replacing a Mutex + var setup when the operations on the state are clearly enumerable as a small set of message types.
• Modeling a stateful service whose state evolves through a stream of commands (AddItem, RemoveItem, Clear, …).
• When StateFlow isn't quite right because the state needs commands, not just observation.

When NOT to use this skill

• The state is observed by many consumers but rarely updated → StateFlow is simpler.
• Operations are independent enough that no coordination is needed → no actor required.
• The state is genuinely complex with many invariants → consider whether a proper data structure with internal locking would be clearer.

Core content