v0.5 Roadmap Tracking Issue

[ElFantasma]

Updated 2026-02-03: Incorporated framework comparison analysis from #124. Added P0 section for critical API issues (#144, #145) that should be addressed before Phase 2. Added priority order table and v0.6+ considerations. See docs/PLAN.md for full analysis.

---

Spawned v0.5 Roadmap

This issue tracks the consolidated v0.5 development plan, informed by analysis of established actor frameworks (Erlang/OTP, Akka, Orleans, Actix, Ractor). See docs/PLAN.md for detailed framework comparison.

---

Phase 1: API Alignment & Actor Rename ✅ Complete

Goal: Make tasks/ and threads/ Actor APIs identical so switching requires only import change + removing async/await.

• Rename GenServer to Actor across codebase #117 - Rename GenServer to Actor across codebase ⚠️ Breaking
• Add call_with_timeout() to threads Actor #118 - Add call_with_timeout() to threads Actor
• Add teardown() callback to threads Actor #119 - Add teardown() callback to threads Actor
• Change threads init() to return InitResult<Self> #120 - Change threads init() to return InitResult<Self> ⚠️ Breaking
• Add send_message_on() to threads Actor #121 - Add send_message_on() to threads Actor
• Align type bounds between tasks and threads Actor traits #122 - Align type bounds between tasks and threads
• Fix send_after/send_interval to respect Actor shutdown in threads #123 - Fix send_after/send_interval to respect Actor shutdown
• Enable Ctrl+C signal handling for start_blocking() #116 - Enable Ctrl+C signal handling for start_blocking() (closes Catch ctrl_c signaling on genservers that where spawned with start_blocking() #58)

---

P0: Critical API Issues 🔴 Not started

Goal: Address foundational API design issues before building more features on top. Fixing these later would be breaking changes.

• Circular dependency problem with bidirectional actor communication #145 - Circular dependency with bidirectional actors

  • ActorRef<T> creates module-level circular deps when actors communicate bidirectionally
  • Blocks real-world collaboration patterns
  • Solution: Type-erased handles (like Actix's Recipient<M>) or PID-based addressing

• Improve type safety for request/reply message handling #144 - Type safety for request/reply

  • Callers must match full Reply enum even when only subset of variants possible
  • Verbose, error-prone code
  • Solution: Per-message response types or derive macro

---

Phase 2: Error Handling & Code Quality 🔴 Not started

Goal: Proper error handling instead of silently dropping channel errors.

• Proper error handling for channel send operations #125 - Proper error handling for channel send operations (closes Handle channel Errors #2)
• Extract Actor tests to separate test files #126 - Extract Actor tests to separate test files

---

Phase 3: Process Primitives 🔴 Not started

Goal: Add core process management while keeping both modules.

• Add Pid (Process Identity) type #127 - Add Pid (Process Identity) type
• Add ActorTable for global actor tracking #128 - Add ActorTable for global actor tracking (closes Add a GenServer registry #33)
• Add Registry for name-based actor lookup #129 - Add Registry for name-based actor lookup
• Add SystemMessage enum for process notifications #130 - Add SystemMessage enum for process notifications
• Add link and monitor operations for actors #131 - Add link and monitor operations to Actor

---

Phase 4: Supervision 🔴 Not started

Goal: Erlang-style fault tolerance.

• Add ChildSpec for supervisor child configuration #132 - Add ChildSpec for supervisor child configuration
• Add Supervisor actor for fault tolerance #133 - Add Supervisor actor for fault tolerance
• Add DynamicSupervisor for runtime child creation #134 - Add DynamicSupervisor for runtime child creation

---

Phase 5: Documentation & Publishing 🔴 Not started

Goal: Improve documentation and publishing.

• Update all examples to use Actor terminology #135 - Update all examples to use Actor terminology
• Add metadata to Cargo.toml manifests #136 - Add metadata to Cargo.toml manifests (closes Add metadata to manifest #63)
• Convert examples to doc tests #137 - Convert examples to doc tests (closes Examples should be doc tests #62)

---

Priority Order

Priority	Phase	Description	Rationale
P0	API Design	#144, #145	Core API issues; breaking changes if deferred
P1	Phase 2	Error Handling	Foundation for supervision
P2	Phase 3	Process Primitives	Building blocks for supervisors
P3	Phase 4	Supervision	Requires P1 + P2
P4	Phase 5	Documentation	After API stabilizes

---

v0.6+ Considerations

Feature	Priority	Notes
State machines (gen_statem)	Medium	Useful for protocol implementations
Backoff strategies	Medium	Akka has this built into supervision
Persistence/event sourcing	Medium	Akka Persistence pattern
Clustering/distribution	Low	Significant complexity

---

Summary

Phase	Focus	Issues	Status
1	API alignment + Actor rename	8	✅ Complete
P0	Critical API issues	2	🔴 Not started
2	Error handling + cleanup	2	🔴 Not started
3	Process primitives	5	🔴 Not started
4	Supervision	3	🔴 Not started
5	Documentation	3	🔴 Not started

Verification (after each phase)

1. cargo build --workspace
2. cargo test --workspace
3. cargo clippy --workspace
4. Run examples

[ElFantasma]

v0.5.0 shipped in PR #153. Roadmap now lives in docs/ROADMAP.md.