gen_state_machine
An idiomatic Elixir wrapper for OTP's gen_statem behavior, providing cleaner syntax and automatic callback mode declaration.
What is gen_state_machine?
GenStateMachine is an Elixir library that provides an idiomatic wrapper around OTP's gen_statem behavior for building state machines. It simplifies the implementation of stateful processes by offering cleaner Elixir syntax while maintaining full compatibility with the underlying Erlang functionality. The library eliminates boilerplate code and provides sensible defaults for common state machine patterns.
Elixir developers building concurrent, stateful applications using OTP behaviors, particularly those who want to use gen_statem with a more Elixir-friendly interface.
Developers choose GenStateMachine because it provides the reliability and power of OTP's gen_statem with an idiomatic Elixir API, reducing boilerplate code and making state machines more accessible while maintaining 100% compatibility with the underlying behavior.
Overview
An idiomatic Elixir wrapper for gen_statem in OTP 19 (and above).
Use Cases
Best For
- Implementing complex state machines in Elixir applications
- Building fault-tolerant concurrent systems using OTP behaviors
- Wrapping existing gen_statem implementations with Elixir syntax
- Creating stateful processes with cleaner callback declarations
- Developing Elixir applications that need reliable state management
- Migrating Erlang gen_statem code to more idiomatic Elixir
Not Ideal For
- Projects that require lightweight, non-OTP state machines for simple in-memory state management
- Teams already using alternative Elixir state machine libraries like Fsm or Machina with established workflows
- Applications stuck on older Erlang/OTP versions below 20, due to compatibility constraints
- Developers seeking a high-level abstraction that completely hides gen_statem complexity, as this is a thin wrapper
Pros & Cons
Pros
Provides an Elixir-friendly API by declaring callback mode via `use GenStateMachine`, eliminating the manual `callback_mode/0` function required in raw gen_statem, making code more readable.
Automatically defines standard default callbacks through the `use` macro, reducing repetitive code and simplifying state machine setup, as highlighted in the README.
Maintains 100% functional compatibility with gen_statem, ensuring all features and reliability of the underlying Erlang behavior are preserved without alterations.
Includes a built-in Logger error translator for better debugging experience, which can be optionally disabled by adjusting application configuration, improving developer workflow.
Cons
Requires OTP 20 or higher, as stated in the README, which may exclude projects on older Erlang/OTP versions and limit adoption in legacy systems.
It doesn't abstract away gen_statem complexity; developers must still understand OTP concepts like callback modes, offering minimal simplification for those new to state machines.
The automatic Logger error translator adds configuration complexity; disabling it requires changing to `:included_applications` in mix.exs, which can be unintuitive and error-prone.
Frequently Asked Questions
Found a gem we're missing?
Open-Awesome is built by the community, for the community. Submit a project, suggest an awesome list, or help improve the catalog on GitHub.