Effective state management in Rust requires balancing between safety, performance, and expressiveness. I’ve spent years refining these techniques in production systems, and each pattern offers unique advantages depending on your application’s needs.
The Type-State Pattern
The type-state pattern leverages Rust’s type system to make invalid states unrepresentable. This pattern uses phantom types to encode state transitions at compile time.
struct Draft;
struct Published;
struct Archived;
struct Document<State> {
content: String,
_state: std::marker::PhantomData<State>,
}
impl Document<Draft> {
fn new(content: String) -> Self {
Document { content, _state: std::marker::PhantomData }
}
fn publish(self) -> Document<Published> {
println!("Publishing document");
Document { content: self.content, _state: std::marker::PhantomData }
}
}
impl Document<Published> {
fn archive(self) -> Document<Archived> {
println!("Archiving document");
Document { content: self.content, _state: std::marker::PhantomData }
}
}
This pattern shines when you need compile-time guarantees about state transitions. I’ve found it particularly useful in APIs where certain operations should only be available in specific states. The compiler prevents any attempt to call methods that aren’t valid for the current state.
Enums for State Machines
For more dynamic state management, enum-based state machines provide a clean, memory-efficient approach:
enum TaskState {
Pending,
Running { started_at: std::time::Instant },
Completed { result: String },
Failed { error: String, retry_count: u32 },
}
struct Task {
id: String,
state: TaskState,
}
impl Task {
fn new(id: String) -> Self {
Self { id, state: TaskState::Pending }
}
fn start(&mut self) {
if let TaskState::Pending = self.state {
self.state = TaskState::Running {
started_at: std::time::Instant::now()
};
}
}
fn complete(&mut self, result: String) {
if let TaskState::Running { .. } = self.state {
self.state = TaskState::Completed { result };
}
}
fn fail(&mut self, error: String) {
self.state = match &self.state {
TaskState::Running { .. } => TaskState::Failed {
error,
retry_count: 0
},
TaskState::Failed { error: prev_error, retry_count } => TaskState::Failed {
error: format!("{prev_error}; {error}"),
retry_count: retry_count + 1
},
_ => return,
};
}
}
I prefer this pattern when states have associated data or when the number of possible transitions is limited. It provides a clear representation of the possible states and allows for exhaustive pattern matching.
Interior Mutability for Shared State
When you need to share state across multiple components or allow mutation through shared references, interior mutability comes into play:
use std::cell::{Cell, RefCell};
struct RequestTracker {
total_requests: Cell<usize>,
active_requests: Cell<usize>,
recent_errors: RefCell<Vec<String>>,
}
impl RequestTracker {
fn new() -> Self {
Self {
total_requests: Cell::new(0),
active_requests: Cell::new(0),
recent_errors: RefCell::new(Vec::new()),
}
}
fn record_request(&self) {
self.total_requests.set(self.total_requests.get() + 1);
self.active_requests.set(self.active_requests.get() + 1);
}
fn complete_request(&self) {
let active = self.active_requests.get();
if active > 0 {
self.active_requests.set(active - 1);
}
}
fn record_error(&self, error: String) {
let mut errors = self.recent_errors.borrow_mut();
errors.push(error);
if errors.len() > 10 {
errors.remove(0);
}
}
fn stats(&self) -> (usize, usize, Vec<String>) {
(
self.total_requests.get(),
self.active_requests.get(),
self.recent_errors.borrow().clone()
)
}
}
I’ve used this pattern extensively in web servers and service contexts where components need to share access to metrics, caches, or configuration. The key is choosing the right cell type - Cell
for Copy types, RefCell
for more complex structures, and their atomic variants for thread-safe code.
Atomic Operations for Thread-Safe State
When concurrency enters the picture, atomic operations provide lock-free state management:
use std::sync::atomic::{AtomicBool, AtomicUsize, Ordering};
struct WorkerPool {
running: AtomicBool,
active_workers: AtomicUsize,
completed_tasks: AtomicUsize,
}
impl WorkerPool {
fn new() -> Self {
Self {
running: AtomicBool::new(true),
active_workers: AtomicUsize::new(0),
completed_tasks: AtomicUsize::new(0),
}
}
fn worker_starting(&self) -> bool {
if !self.running.load(Ordering::Relaxed) {
return false;
}
self.active_workers.fetch_add(1, Ordering::Relaxed);
true
}
fn worker_stopping(&self) {
self.active_workers.fetch_sub(1, Ordering::Relaxed);
}
fn task_completed(&self) {
self.completed_tasks.fetch_add(1, Ordering::Relaxed);
}
fn shutdown(&self) {
self.running.store(false, Ordering::Relaxed);
}
fn stats(&self) -> (bool, usize, usize) {
(
self.running.load(Ordering::Relaxed),
self.active_workers.load(Ordering::Relaxed),
self.completed_tasks.load(Ordering::Relaxed)
)
}
}
When I built a high-throughput job processing system, atomic state management was crucial for maintaining performance. This approach avoids the overhead of locks while providing thread-safe state transitions.
Command Pattern for State History
The command pattern encapsulates state changes as discrete, reversible operations:
enum EditorCommand {
Insert { position: usize, text: String },
Delete { position: usize, length: usize, deleted_text: String },
SetSelection { start: usize, end: usize },
}
struct TextEditor {
content: String,
selection: (usize, usize),
history: Vec<EditorCommand>,
redo_stack: Vec<EditorCommand>,
}
impl TextEditor {
fn new() -> Self {
Self {
content: String::new(),
selection: (0, 0),
history: Vec::new(),
redo_stack: Vec::new(),
}
}
fn execute(&mut self, command: EditorCommand) {
match &command {
EditorCommand::Insert { position, text } => {
self.content.insert_str(*position, text);
},
EditorCommand::Delete { position, length, .. } => {
let deleted = self.content.drain(*position..*position + *length).collect();
// Store the deleted text for undo
let command = EditorCommand::Delete {
position: *position,
length: *length,
deleted_text: deleted,
};
self.history.pop(); // Remove the placeholder
self.history.push(command);
return;
},
EditorCommand::SetSelection { start, end } => {
self.selection = (*start, *end);
}
}
self.history.push(command);
self.redo_stack.clear();
}
fn delete_selection(&mut self) {
let (start, end) = self.selection;
if start != end {
// First push a placeholder that will be replaced
self.execute(EditorCommand::Delete {
position: start,
length: end - start,
deleted_text: String::new(),
});
}
}
fn undo(&mut self) {
if let Some(command) = self.history.pop() {
match command {
EditorCommand::Insert { position, text } => {
self.content.replace_range(position..position + text.len(), "");
},
EditorCommand::Delete { position, length: _, deleted_text } => {
self.content.insert_str(position, &deleted_text);
},
EditorCommand::SetSelection { .. } => {
// Restore previous selection if available
if let Some(EditorCommand::SetSelection { start, end }) =
self.history.iter().rev().find(|cmd| matches!(cmd, EditorCommand::SetSelection { .. })) {
self.selection = (*start, *end);
} else {
self.selection = (0, 0);
}
}
}
self.redo_stack.push(command);
}
}
}
I’ve implemented this pattern in document editors and workflow systems where operations need to be tracked, undone, or replayed. It provides a clean separation between the operations themselves and the state they modify.
Hierarchical State Composition
Complex applications often benefit from breaking state into manageable components:
struct ApplicationState {
user: UserState,
documents: DocumentState,
network: NetworkState,
}
struct UserState {
current_user: Option<User>,
permissions: Vec<Permission>,
login_attempts: usize,
}
struct User {
id: String,
name: String,
email: String,
}
enum Permission {
Read,
Write,
Admin,
}
struct DocumentState {
open_documents: Vec<Document>,
current_document_index: Option<usize>,
unsaved_changes: bool,
}
struct Document {
id: String,
title: String,
content: String,
}
enum NetworkState {
Connected { latency_ms: u64 },
Disconnected { retry_count: usize },
Offline,
}
impl ApplicationState {
fn new() -> Self {
Self {
user: UserState {
current_user: None,
permissions: Vec::new(),
login_attempts: 0,
},
documents: DocumentState {
open_documents: Vec::new(),
current_document_index: None,
unsaved_changes: false,
},
network: NetworkState::Offline,
}
}
fn can_edit_document(&self) -> bool {
self.user.permissions.contains(&Permission::Write) &&
self.documents.current_document_index.is_some() &&
matches!(self.network, NetworkState::Connected { .. })
}
fn set_network_status(&mut self, connected: bool, latency: Option<u64>) {
self.network = if connected {
NetworkState::Connected { latency_ms: latency.unwrap_or(100) }
} else {
match self.network {
NetworkState::Disconnected { retry_count } if retry_count < 3 => {
NetworkState::Disconnected { retry_count: retry_count + 1 }
}
NetworkState::Connected { .. } => NetworkState::Disconnected { retry_count: 1 },
_ => NetworkState::Offline,
}
};
}
}
This approach has saved me countless hours when building complex applications. By structuring state hierarchically, you can reason about each component independently while still maintaining the relationships between them.
Rust’s ownership model makes these patterns particularly powerful. By choosing the right pattern for each part of your application, you can create state management solutions that are both safe and efficient. I’ve found the best designs often combine multiple patterns, applying each where it makes the most sense.
In my experience, good state management is about making invalid states unrepresentable while keeping the code readable and maintainable. These six patterns provide the foundation for achieving that balance in Rust applications.