feat: add send_info_after() to GenServerContext for scheduled info messages

- Add send_info_after() method to GenServerContext for scheduling info messages
- Add whereis() method to GenServerContext for name lookup
- Update gen_server_self_message example to demonstrate scheduled messaging
- Example now shows both immediate (cast) and scheduled (send_info_after) patterns
- Properly wraps messages in GenServerMsg::Info for handle_info() delivery

This enables GenServers to easily schedule periodic tasks and delayed operations
to themselves using the scheduler, matching Erlang's timer:send_after/2 pattern.

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

Author: am-kantox

joerl/examples/gen_server_self_message.rs

@@ -1,21 +1,23 @@
 //! Example: GenServer sending messages to itself
 //!
-//! Demonstrates a GenServer that sends cast messages to itself to implement
-//! a self-incrementing counter loop.
+//! Demonstrates two patterns for GenServer self-messaging:
+//! 1. Using cast() to send immediate messages to itself
+//! 2. Using send_after() to schedule delayed messages (via scheduler)
 //!
 //! This pattern is useful for:
 //! - Background processing loops
-//! - Periodic tasks without using timers
+//! - Periodic tasks and timers
 //! - State machines that need to trigger their own state transitions
 //! - Work queues that process items sequentially
 
 use async_trait::async_trait;
-use joerl::gen_server::{CallResponse, GenServer, GenServerContext, GenServerRef, spawn};
-use joerl::{ActorSystem, ExitReason};
+use joerl::gen_server::{spawn, CallResponse, GenServer, GenServerContext, GenServerRef};
+use joerl::{ActorSystem, ExitReason, Message};
 use std::sync::Arc;
+use std::time::Duration;
 
 // ============================================================================
-// Self-Incrementing Counter
+// Example 1: Immediate self-messaging with cast()
 // ============================================================================
 
 struct Counter;
@@ -107,12 +109,108 @@ impl GenServer for Counter {
     }
 }
 
+// ============================================================================
+// Example 2: Scheduled self-messaging with send_after()
+// ============================================================================
+
+struct Ticker;
+
+#[derive(Debug)]
+enum TickerCall {
+    Start,
+}
+
+#[derive(Debug)]
+enum TickerCast {}
+
+#[async_trait]
+impl GenServer for Ticker {
+    type State = (u32, u32); // (tick_count, max_ticks)
+    type Call = TickerCall;
+    type Cast = TickerCast;
+    type CallReply = u32;
+
+    async fn init(&mut self, _ctx: &mut GenServerContext<'_, Self>) -> Self::State {
+        println!("[Ticker] Initializing");
+        (0, 5) // Start at 0, max 5 ticks
+    }
+
+    async fn handle_call(
+        &mut self,
+        call: Self::Call,
+        state: &mut Self::State,
+        ctx: &mut GenServerContext<'_, Self>,
+    ) -> CallResponse<Self::CallReply> {
+        match call {
+            TickerCall::Start => {
+                println!("[Ticker] Starting periodic ticker");
+                // Schedule first tick to ourselves after 100ms using send_info_after
+                let timer_ref = ctx.send_info_after(
+                    Box::new("tick"),
+                    Duration::from_millis(100),
+                );
+                println!("[Ticker] Scheduled timer: {:?}", timer_ref);
+                CallResponse::Reply(state.0)
+            }
+        }
+    }
+
+    async fn handle_cast(
+        &mut self,
+        _cast: Self::Cast,
+        _state: &mut Self::State,
+        _ctx: &mut GenServerContext<'_, Self>,
+    ) {
+        // No casts for this server
+    }
+
+    async fn handle_info(
+        &mut self,
+        msg: Message,
+        state: &mut Self::State,
+        ctx: &mut GenServerContext<'_, Self>,
+    ) {
+        // Handle scheduled "tick" messages
+        if let Some(tick) = msg.downcast_ref::<&str>()
+            && *tick == "tick"
+        {
+            state.0 += 1;
+            println!("[Ticker] Tick #{}", state.0);
+
+            if state.0 < state.1 {
+                // Schedule next tick after 100ms using send_info_after
+                ctx.send_info_after(Box::new("tick"), Duration::from_millis(100));
+            } else {
+                println!("[Ticker] Reached max ticks ({}), stopping", state.1);
+                ctx.stop(ExitReason::Normal);
+            }
+        }
+    }
+
+    async fn terminate(
+        &mut self,
+        reason: &ExitReason,
+        state: &mut Self::State,
+        _ctx: &mut GenServerContext<'_, Self>,
+    ) {
+        println!(
+            "[Ticker] Terminated with reason: {}, final ticks: {}",
+            reason, state.0
+        );
+    }
+}
+
 #[tokio::main]
 async fn main() {
-    println!("=== GenServer Self-Messaging Example ===\n");
+    println!("=== GenServer Self-Messaging Examples ===\n");
 
     let system = Arc::new(ActorSystem::new());
 
+    // ========================================================================
+    // Example 1: Immediate self-messaging with cast()
+    // ========================================================================
+    println!("--- Example 1: Immediate Self-Messaging ---");
+
     // Spawn the counter GenServer
     let counter_ref = spawn(&system, Counter);
     println!("[Main] Spawned counter with PID: {}\n", counter_ref.pid());
@@ -129,7 +227,22 @@ async fn main() {
         .await;
 
     // Wait for the counter to finish (it will stop itself at max value)
-    tokio::time::sleep(tokio::time::Duration::from_millis(800)).await;
+    tokio::time::sleep(Duration::from_millis(200)).await;
+
+    // ========================================================================
+    // Example 2: Scheduled self-messaging with send_after()
+    // ========================================================================
+    println!("\n--- Example 2: Scheduled Self-Messaging (Ticker) ---");
+
+    // Spawn the ticker GenServer
+    let ticker_ref = spawn(&system, Ticker);
+    println!("[Main] Spawned ticker with PID: {}\n", ticker_ref.pid());
+
+    // Start the periodic ticker
+    let _ = ticker_ref.call(TickerCall::Start).await;
+
+    // Wait for ticks to complete (5 ticks * 100ms + buffer)
+    tokio::time::sleep(Duration::from_millis(650)).await;
 
-    println!("\n=== Example completed ===");
+    println!("\n=== All examples completed ===");
 }

joerl/src/gen_server.rs

@@ -404,6 +404,155 @@ impl<'a, G: GenServer> GenServerContext<'a, G> {
             .take()
             .expect("reply_handle() called outside handle_call or already taken")
     }
+
+    /// Looks up a process by name.
+    ///
+    /// Returns the Pid if the name is registered, or None otherwise.
+    ///
+    /// In Erlang: `whereis(Name)`
+    pub fn whereis(&self, name: &str) -> Option<Pid> {
+        self.actor_ctx.whereis(name)
+    }
+
+    /// Schedules a message to be sent after a delay.
+    ///
+    /// Returns a TimerRef that can be used to cancel the timer.
+    ///
+    /// In Erlang: `erlang:send_after(Time, Dest, Message)`
+    ///
+    /// # Examples
+    ///
+    /// ```rust
+    /// use joerl::gen_server::{GenServer, GenServerContext, CallResponse};
+    /// use joerl::scheduler::Destination;
+    /// use joerl::Message;
+    /// use async_trait::async_trait;
+    /// use std::time::Duration;
+    ///
+    /// struct TimerServer;
+    ///
+    /// #[derive(Debug)]
+    /// enum Call { Start }
+    ///
+    /// #[derive(Debug)]
+    /// enum Cast {}
+    ///
+    /// #[async_trait]
+    /// impl GenServer for TimerServer {
+    ///     type State = u32;
+    ///     type Call = Call;
+    ///     type Cast = Cast;
+    ///     type CallReply = ();
+    ///
+    ///     async fn init(&mut self, _ctx: &mut GenServerContext<'_, Self>) -> Self::State {
+    ///         0
+    ///     }
+    ///
+    ///     async fn handle_call(
+    ///         &mut self,
+    ///         _call: Self::Call,
+    ///         _state: &mut Self::State,
+    ///         ctx: &mut GenServerContext<'_, Self>,
+    ///     ) -> CallResponse<Self::CallReply> {
+    ///         // Schedule a message to ourselves
+    ///         ctx.send_after(
+    ///             Destination::Pid(ctx.pid()),
+    ///             Box::new("tick"),
+    ///             Duration::from_secs(1)
+    ///         );
+    ///         CallResponse::Reply(())
+    ///     }
+    ///
+    ///     async fn handle_cast(&mut self, _cast: Self::Cast, _state: &mut Self::State, _ctx: &mut GenServerContext<'_, Self>) {}
+    /// }
+    /// ```
+    pub fn send_after(
+        &self,
+        dest: crate::scheduler::Destination,
+        msg: Message,
+        duration: std::time::Duration,
+    ) -> Option<crate::scheduler::TimerRef> {
+        self.actor_ctx.send_after(dest, msg, duration)
+    }
+
+    /// Schedules an info message to be sent to this GenServer after a delay.
+    ///
+    /// This is a convenience wrapper that properly wraps the message in `GenServerMsg::Info`
+    /// so it will be delivered to `handle_info()`. Use this instead of `send_after()` when
+    /// scheduling messages to GenServers.
+    ///
+    /// Returns a TimerRef that can be used to cancel the timer.
+    ///
+    /// In Erlang: `erlang:send_after(Time, self(), Message)` for info messages
+    ///
+    /// # Examples
+    ///
+    /// ```rust
+    /// use joerl::gen_server::{GenServer, GenServerContext, CallResponse};
+    /// use joerl::Message;
+    /// use async_trait::async_trait;
+    /// use std::time::Duration;
+    ///
+    /// struct TickerServer;
+    ///
+    /// #[derive(Debug)]
+    /// enum Call { Start }
+    ///
+    /// #[derive(Debug)]
+    /// enum Cast {}
+    ///
+    /// #[async_trait]
+    /// impl GenServer for TickerServer {
+    ///     type State = u32;
+    ///     type Call = Call;
+    ///     type Cast = Cast;
+    ///     type CallReply = ();
+    ///
+    ///     async fn init(&mut self, _ctx: &mut GenServerContext<'_, Self>) -> Self::State {
+    ///         0
+    ///     }
+    ///
+    ///     async fn handle_call(
+    ///         &mut self,
+    ///         _call: Self::Call,
+    ///         _state: &mut Self::State,
+    ///         ctx: &mut GenServerContext<'_, Self>,
+    ///     ) -> CallResponse<Self::CallReply> {
+    ///         // Schedule an info message to ourselves
+    ///         ctx.send_info_after(
+    ///             Box::new("tick"),
+    ///             Duration::from_secs(1)
+    ///         );
+    ///         CallResponse::Reply(())
+    ///     }
+    ///
+    ///     async fn handle_cast(&mut self, _cast: Self::Cast, _state: &mut Self::State, _ctx: &mut GenServerContext<'_, Self>) {}
+    ///
+    ///     async fn handle_info(
+    ///         &mut self,
+    ///         msg: Message,
+    ///         state: &mut Self::State,
+    ///         _ctx: &mut GenServerContext<'_, Self>,
+    ///     ) {
+    ///         if let Some(_tick) = msg.downcast_ref::<&str>() {
+    ///             *state += 1;
+    ///         }
+    ///     }
+    /// }
+    /// ```
+    pub fn send_info_after(
+        &self,
+        msg: Message,
+        duration: std::time::Duration,
+    ) -> Option<crate::scheduler::TimerRef> {
+        // Wrap the message in GenServerMsg::Info so handle_info will receive it
+        let info_msg: GenServerMsg<G> = GenServerMsg::Info { message: msg };
+        self.actor_ctx.send_after(
+            crate::scheduler::Destination::Pid(self.pid()),
+            Box::new(info_msg),
+            duration,
+        )
+    }
 }
 
 /// Internal message types for GenServer