rs-statemachine with Feature Flags
A flexible and extensible state machine implementation for Rust with optional advanced features that can be enabled through Cargo feature flags.
This project was inspired by the cola project.
Features
The library provides a core state machine implementation with the following optional features:
| Feature | Description | Default |
|---|---|---|
history |
Track state transition history | ✓ |
extended |
Entry/exit actions for states | ✓ |
metrics |
Performance metrics collection | ✓ |
hierarchical |
Hierarchical state support | |
guards |
Guard conditions with priorities | |
timeout |
State timeout support | |
parallel |
Parallel state regions | |
visualization |
Export to DOT/PlantUML formats | |
serde |
Serialization support | |
async |
Async action support | |
full |
Enable all features |
Installation
Add this to your Cargo.toml:
[]
# Basic installation with default features
= "0.1"
# Or with specific features
= { = "0.1", = ["history", "metrics", "visualization"] }
# Or with all features
= { = "0.1", = ["full"] }
# Minimal installation (no features)
= { = "0.1", = false }
Basic Usage
use *;
// Define your states
// Define your events
// Define your context
// Build the state machine
let mut builder = ;
builder
.external_transition
.from
.to
.on
.perform;
let state_machine = builder.build;
Feature Examples
History Tracking (history feature)
Entry/Exit Actions (extended feature)
Metrics Collection (metrics feature)
Guard Priorities (guards feature)
Visualization (visualization feature)
Parallel Regions (parallel feature)
Async Support (async feature)
Performance Considerations
- Minimal Core: The core state machine has minimal overhead when features are disabled
- Feature Cost: Each feature adds some memory and computational overhead:
history: Stores transition records in memorymetrics: Tracks timing and countersextended: Adds hashmap lookups for entry/exit actionsguards: Adds sorting step for priority evaluation
Building Without Default Features
To use only the core state machine without any additional features:
[]
= { = "0.1", = false }
Then selectively enable only the features you need:
[]
= { = "0.1", = false, = ["visualization"] }
Feature Combinations
Some features work well together:
history+metrics: Complete audit trail with performance dataextended+guards: Complex state logic with entry/exit actionsvisualization+ any: Visualize your state machine configurationasync+timeout: Handle long-running operations with timeouts
Migration Guide
If you're migrating from a version without feature flags:
- The core API remains unchanged
- Advanced features that were previously in separate modules are now behind feature flags
- Default features (
history,extended,metrics) provide common functionality - Use
features = ["full"]to enable everything
Contributing
When adding new features:
- Add a new feature flag in
Cargo.toml - Gate the implementation with
#[cfg(feature = "your_feature")] - Update documentation and examples
- Ensure the core functionality works without your feature
License
This project is licensed under the MIT License - see the LICENSE file for details.