feat: add named process registry and scheduled messaging

- Add Registry for actor name registration (register, whereis, unregister)
- Add Scheduler for delayed message delivery (send_after, cancel_timer)
- Add ActorContext methods for registry and scheduler access
- Add telemetry metrics for registry and scheduler operations
- Add comprehensive integration tests and examples
- Fix doctest compilation errors in scheduler.rs and system.rs

This implements Erlang-style named processes and timer functionality,
enabling location-transparent messaging and delayed message delivery.

Co-Authored-By: Warp <agent@warp.dev>

Author: am-kantox

Cargo.lock

@@ -0,0 +1,124 @@
+# Overview
+Implement Erlang-style named process registry and scheduled messaging to make joerl more feature-complete for Erlang developers. This includes:
+* `whereis/1` - Look up processes by registered name
+* `register/2` - Register a process with a name
+* `unregister/1` - Unregister a named process
+* `send/2` - Send to named process or Pid
+* `send_after/3` - Schedule a message to be sent after a delay
+# Current State
+joerl currently only supports addressing actors by Pid. The ActorSystem maintains a DashMap registry mapping Pid to ActorEntry (joerl/src/system.rs:279). Messages are sent via `ActorSystem::send()` and `ActorRef::send()` methods which only accept Pid as the recipient.
+There is no timer/scheduler subsystem, and all message sending is immediate.
+# Proposed Changes
+## 1. Create Named Registry Module
+Create joerl/src/registry.rs for name registration functionality.
+### Registry Structure
+* Use `DashMap<String, Pid>` for thread-safe name-to-Pid mapping
+* Use `DashMap<Pid, String>` for reverse lookup (Pid-to-name)
+* Support both local and distributed names (node-scoped)
+* Automatic cleanup when actors terminate
+### Key Types
+* `RegisteredName` - Newtype wrapper for registered names with validation
+* `RegistrationError` - Specific errors for name conflicts, invalid names
+### Core Functions
+* `register(name: String, pid: Pid) -> Result<()>` - Register name (error if already registered)
+* `unregister(name: &str) -> Result<Pid>` - Remove registration, return Pid
+* `whereis(name: &str) -> Option<Pid>` - Look up Pid by name
+* `registered() -> Vec<String>` - List all registered names
+* `cleanup_pid(pid: Pid)` - Internal cleanup when actor dies
+## 2. Integrate Registry into ActorSystem
+Add registry field to ActorSystem (joerl/src/system.rs:278).
+### Changes to ActorSystem
+* Add `registry: Arc<Registry>` field
+* Initialize registry in `new()` and `new_distributed()`
+* Expose public API methods that delegate to registry:
+    * `register(&self, name: impl Into<String>, pid: Pid) -> Result<()>`
+    * `unregister(&self, name: &str) -> Result<Pid>`
+    * `whereis(&self, name: &str) -> Option<Pid>`
+    * `registered(&self) -> Vec<String>`
+* Call `registry.cleanup_pid()` in `cleanup_actor()` (system.rs:717)
+### Named Send Support
+* Create `Destination` enum: `Pid(Pid) | Name(String)`
+* Add `send_to(&self, dest: Destination, msg: Message) -> Result<()>`
+* Modify existing `send()` to work through this abstraction
+* Update ActorRef to support named sends
+## 3. Create Scheduler Module
+Create joerl/src/scheduler.rs for delayed message scheduling.
+### Scheduler Structure
+* Use tokio's time utilities (`tokio::time::sleep`, `Instant`)
+* Store scheduled messages as heap-ordered by delivery time
+* Each scheduled message spawns a tokio task that sleeps then sends
+### Key Types
+* `ScheduledMessage` - Contains destination, message, delivery time
+* `SchedulerHandle` - Cancellable reference to scheduled message
+* `TimerRef` - Erlang-style timer reference for cancellation
+### Core Functions
+* `send_after(dest: Destination, msg: Message, duration: Duration) -> TimerRef`
+* `cancel_timer(timer_ref: TimerRef) -> Result<bool>` - Returns true if cancelled
+* `send_interval(dest: Destination, msg: Message, interval: Duration) -> TimerRef` (bonus)
+### Implementation Strategy
+* Each `send_after` spawns a detached tokio task
+* Task sleeps for duration, then calls `ActorSystem::send_to()`
+* Store cancellation tokens in `DashMap<TimerRef, CancellationToken>`
+* Use `tokio_util::sync::CancellationToken` for cancellation
+## 4. Update Message Types
+Add timer-related message types to joerl/src/message.rs if needed for timer expiry notifications.
+## 5. Extend ActorContext
+Add convenience methods to ActorContext (joerl/src/actor.rs:100):
+* `send_after(&self, dest: Destination, msg: Message, duration: Duration) -> Result<TimerRef>`
+* `whereis(&self, name: &str) -> Option<Pid>`
+* Allow actors to easily schedule messages from within their context
+## 6. Update Error Types
+Add new error variants to ActorError (joerl/src/error.rs):
+* `NameAlreadyRegistered(String)`
+* `NameNotRegistered(String)`
+* `InvalidName(String)`
+* `TimerNotFound(u64)`
+## 7. Telemetry Integration
+Add metrics for registry and scheduler (if telemetry feature enabled):
+* `joerl_registry_size` - Current number of registered names
+* `joerl_registry_lookups_total` - Registry lookup counter
+* `joerl_registry_conflicts_total` - Registration conflict counter
+* `joerl_scheduled_messages_total` - Messages scheduled
+* `joerl_scheduled_messages_cancelled_total` - Timers cancelled
+## 8. Documentation and Examples
+### Update README.md
+Add section on named processes and scheduled messaging with examples.
+### Create Examples
+* `examples/named_processes.rs` - Registry demonstration
+* `examples/scheduled_messaging.rs` - Timer demonstration
+* Update existing examples to show optional use of names
+### Update Erlang Terminology Mapping
+Add to README.md (line 301):
+* `register(Name, Pid)` -> `system.register(name, pid)`
+* `unregister(Name)` -> `system.unregister(name)`
+* `whereis(Name)` -> `system.whereis(name)`
+* `registered()` -> `system.registered()`
+* `erlang:send_after(Time, Pid, Msg)` -> `system.send_after(dest, msg, duration)`
+* `erlang:cancel_timer(TRef)` -> `system.cancel_timer(tref)`
+### Update WARP.md
+Document the new registry and scheduler modules in the Architecture section.
+## 9. Testing
+### Registry Tests
+* Test basic register/unregister/whereis
+* Test name conflicts (should error)
+* Test automatic cleanup on actor death
+* Test concurrent registration attempts
+* Test distributed name registration (node-scoped)
+* Property tests for registry consistency
+### Scheduler Tests
+* Test basic send_after delivery
+* Test timer cancellation before delivery
+* Test message ordering with multiple scheduled messages
+* Test scheduled message to named destination
+* Test scheduled messages survive actor restarts
+* Test timer behaviour when destination dies
+### Integration Tests
+* Named processes with supervision trees
+* Scheduled messages in distributed systems
+* Registry with monitors and links
+## 10. Export Public API
+Update joerl/src/lib.rs:
+* Add `pub mod registry;`
+* Add `pub mod scheduler;`
+* Re-export key types: `RegisteredName`, `Destination`, `TimerRef`
+* Update documentation with new capabilities

NAMED_PROCESSES.md

@@ -278,6 +278,87 @@ The macro generates:
 - `TransitionResult` enum for transition outcomes
 - Boilerplate Actor implementation with validation
 
+### Named Processes
+
+Like Erlang, joerl supports registering actors with names for easy lookup:
+
+```rust
+let system = ActorSystem::new();
+let worker = system.spawn(Worker);
+
+// Register with a name
+system.register("my_worker", worker.pid()).unwrap();
+
+// Look up by name
+if let Some(pid) = system.whereis("my_worker") {
+    system.send(pid, Box::new("Hello")).await?;
+}
+
+// List all registered names
+let names = system.registered();
+
+// Unregister
+system.unregister("my_worker").unwrap();
+```
+
+Names are automatically cleaned up when actors terminate. Actors can look up names from within their context:
+
+```rust
+#[async_trait]
+impl Actor for MyActor {
+    async fn handle_message(&mut self, msg: Message, ctx: &mut ActorContext) {
+        if let Some(manager_pid) = ctx.whereis("manager") {
+            ctx.send(manager_pid, Box::new("status")).await.ok();
+        }
+    }
+}
+```
+
+### Scheduled Messaging
+
+joerl supports Erlang-style `send_after` for delayed message delivery:
+
+```rust
+use joerl::scheduler::Destination;
+use std::time::Duration;
+
+let system = ActorSystem::new();
+let actor = system.spawn(Worker);
+
+// Schedule a message to be sent after 5 seconds
+let timer_ref = system.send_after(
+    Destination::Pid(actor.pid()),
+    Box::new("delayed message"),
+    Duration::from_secs(5)
+).await;
+
+// Cancel the timer if needed
+system.cancel_timer(timer_ref)?;
+
+// Schedule to a named process
+system.send_after(
+    Destination::Name("worker".to_string()),
+    Box::new("task"),
+    Duration::from_millis(100)
+).await;
+```
+
+Actors can schedule messages from within their context:
+
+```rust
+#[async_trait]
+impl Actor for MyActor {
+    async fn started(&mut self, ctx: &mut ActorContext) {
+        // Schedule a reminder to ourselves
+        ctx.send_after(
+            Destination::Pid(ctx.pid()),
+            Box::new("timeout"),
+            Duration::from_secs(10)
+        );
+    }
+}
+```
+
 ### Trapping Exits
 
 Actors can trap exit signals to handle failures gracefully:
@@ -301,6 +382,12 @@ impl Actor for MyActor {
 || Erlang | joerl | Description |
 |--------|-------|-------------|
 | `spawn/1` | `system.spawn(actor)` | Spawn a new actor |
+| `register(Name, Pid)` | `system.register(name, pid)` | Register a process with a name |
+| `unregister(Name)` | `system.unregister(name)` | Unregister a name |
+| `whereis(Name)` | `system.whereis(name)` | Look up a process by name |
+| `registered()` | `system.registered()` | List all registered names |
+| `erlang:send_after(Time, Dest, Msg)` | `system.send_after(dest, msg, duration)` | Schedule delayed message |
+| `erlang:cancel_timer(TRef)` | `system.cancel_timer(tref)` | Cancel a scheduled timer |
 | `gen_server:start_link/3` | `gen_server::spawn(&system, server)` | Spawn a gen_server |
 | `gen_server:call/2` | `server_ref.call(request)` | Synchronous call |
 | `gen_server:cast/2` | `server_ref.cast(message)` | Asynchronous cast |
@@ -325,6 +412,8 @@ See the [`examples/`](examples/) directory for more examples:
 - `ping_pong.rs` - Two actors communicating
 - `supervision_tree.rs` - Supervision tree example
 - `link_monitor.rs` - Links and monitors demonstration
+- `named_processes.rs` - Named process registry demonstration
+- `scheduled_messaging.rs` - Delayed message delivery with timers
 - **`panic_handling.rs` - Comprehensive panic handling demonstration (Erlang/OTP-style)**
 - **`telemetry_demo.rs` - Telemetry and metrics with Prometheus export**
 - `serialization_example.rs` - Trait-based message serialization

README.md

@@ -13,6 +13,7 @@ categories = ["asynchronous", "concurrency"]
 
 [dependencies]
 tokio = { version = "1.48", features = ["full"] }
+tokio-util = "0.7"
 thiserror = "2.0"
 tracing = "0.1"
 async-trait = "0.1"

joerl/Cargo.toml

@@ -0,0 +1,43 @@
+use async_trait::async_trait;
+use joerl::{Actor, ActorContext, ActorSystem, ExitReason, Message};
+
+struct SelfMessenger {
+    count: u32,
+    max: u32,
+}
+
+#[async_trait]
+impl Actor for SelfMessenger {
+    async fn started(&mut self, ctx: &mut ActorContext) {
+        println!("[{}] Starting, sending first message to self", ctx.pid());
+        // Send initial message to self
+        ctx.send(ctx.pid(), Box::new("tick")).await.ok();
+    }
+
+    async fn handle_message(&mut self, msg: Message, ctx: &mut ActorContext) {
+        if let Some(cmd) = msg.downcast_ref::<&str>()
+            && *cmd == "tick"
+        {
+            self.count += 1;
+            println!("[{}] Tick #{}", ctx.pid(), self.count);
+
+            if self.count < self.max {
+                // Send next message to self
+                ctx.send(ctx.pid(), Box::new("tick")).await.ok();
+            } else {
+                println!("[{}] Max reached, stopping", ctx.pid());
+                ctx.stop(ExitReason::Normal);
+            }
+        }
+    }
+}
+
+#[tokio::main]
+async fn main() {
+    let system = ActorSystem::new();
+    let actor = system.spawn(SelfMessenger { count: 0, max: 5 });
+
+    // Wait for the actor to finish
+    let exit_reason = actor.join().await;
+    println!("Done! Actor exited with: {}", exit_reason);
+}