Add ViaRegistry trait, Name enum, and opts builders for named process registration

Brings Elixir-style `name:` option to GenServer, Supervisor, and
DynamicSupervisor start functions. Processes are auto-registered after
init and auto-unregistered after terminate.

- ViaRegistry trait for pluggable registry backends (bound-name pattern)
- ServerRef::Via variant for addressing via custom registries
- Registry::via() method to produce Arc<dyn ViaRegistry> from a Registry
- StartOpts builder for GenServer (.name(), .link(), .start::<G>())
- SupervisorStartOpts builder for Supervisor (.name(), .link(), .start::<S>())
- DynamicSupervisorOpts.name() builder method
- Error::AlreadyStarted variant for duplicate name registration
- Job queue example updated to use builders instead of manual register

Author: scrogson

crates/ambitious/src/gen_server/mod.rs

@@ -88,10 +88,14 @@ mod server_ref;
 mod traits;
 mod types;
 
+/// Pluggable registry support and named process registration.
+pub mod via;
+
 // Primary exports
-pub use server::{Error, call, cast, reply, start, start_link, stop};
+pub use server::{Error, StartOpts, call, cast, reply, start, start_link, stop};
 pub use server_ref::ServerRef;
 pub use traits::GenServer;
+pub use via::{AlreadyRegistered, Name, ViaRegistry};
 
 pub use async_trait::async_trait;
 pub use protocol::From;
@@ -108,8 +112,8 @@ pub use crate::core::{ExitReason, Pid, Ref, Term};
 /// ```
 pub mod prelude {
     pub use super::{
-        Error, ExitReason, From, GenServer, Init, Pid, Reply, ServerRef, Status, async_trait, call,
-        cast, reply, start, start_link, stop,
+        Error, ExitReason, From, GenServer, Init, Name, Pid, Reply, ServerRef, StartOpts, Status,
+        ViaRegistry, async_trait, call, cast, reply, start, start_link, stop,
     };
 }
 

crates/ambitious/src/gen_server/server.rs

@@ -11,6 +11,7 @@ use super::protocol::{
 };
 use super::traits::GenServer;
 use super::types::{Init, Reply, Status};
+use super::via::{Name, register_name, unregister_name};
 use crate::core::{DecodeError, ExitReason, Pid, Ref, Term};
 use crate::message::Message;
 use crate::process::global;
@@ -37,6 +38,58 @@ pub enum Error {
     /// Decode error.
     #[error("decode error: {0}")]
     Decode(#[from] DecodeError),
+    /// The process name is already registered.
+    #[error("already started")]
+    AlreadyStarted,
+}
+
+/// Options for starting a GenServer.
+///
+/// # Example
+///
+/// ```ignore
+/// use ambitious::gen_server::{StartOpts, Name};
+///
+/// let pid = StartOpts::new(42)
+///     .name(Name::local("counter"))
+///     .link()
+///     .start::<Counter>()
+///     .await?;
+/// ```
+pub struct StartOpts<A> {
+    args: A,
+    name: Option<Name>,
+    link: bool,
+}
+
+impl<A: Send + 'static> StartOpts<A> {
+    /// Create start options with the given args.
+    pub fn new(args: A) -> Self {
+        Self {
+            args,
+            name: None,
+            link: false,
+        }
+    }
+
+    /// Register the process under the given name after init succeeds.
+    pub fn name(mut self, name: Name) -> Self {
+        self.name = Some(name);
+        self
+    }
+
+    /// Link the spawned process to the caller.
+    pub fn link(mut self) -> Self {
+        self.link = true;
+        self
+    }
+
+    /// Start the GenServer with these options.
+    ///
+    /// Returns `Error::AlreadyStarted` if a `name` was set and is already taken.
+    pub async fn start<G: GenServer<Args = A>>(self) -> Result<Pid, Error> {
+        start_impl::<G>(self.args, self.name, self.link).await
+    }
 }
 
 /// Start a GenServer process (not linked to caller).
@@ -47,17 +100,21 @@ pub enum Error {
 /// let pid = start::<Counter>(42).await?;
 /// ```
 pub async fn start<G: GenServer>(args: G::Args) -> Result<Pid, Error> {
-    start_impl::<G>(args, false).await
+    start_impl::<G>(args, None, false).await
 }
 
 /// Start a GenServer process linked to the caller.
 ///
 /// If the GenServer crashes, the caller will also crash (unless trapping exits).
 pub async fn start_link<G: GenServer>(args: G::Args) -> Result<Pid, Error> {
-    start_impl::<G>(args, true).await
+    start_impl::<G>(args, None, true).await
 }
 
-async fn start_impl<G: GenServer>(args: G::Args, link: bool) -> Result<Pid, Error> {
+async fn start_impl<G: GenServer>(
+    args: G::Args,
+    name: Option<Name>,
+    link: bool,
+) -> Result<Pid, Error> {
     use tokio::sync::oneshot;
     let (init_tx, init_rx) = oneshot::channel();
 
@@ -71,11 +128,11 @@ async fn start_impl<G: GenServer>(args: G::Args, link: bool) -> Result<Pid, Erro
             ))
         })?;
         handle.spawn_link(parent, move || async move {
-            gen_server_main::<G>(args, Some(init_tx)).await;
+            gen_server_main::<G>(args, name, Some(init_tx)).await;
         })
     } else {
         handle.spawn(move || async move {
-            gen_server_main::<G>(args, Some(init_tx)).await;
+            gen_server_main::<G>(args, name, Some(init_tx)).await;
         })
     };
 
@@ -91,30 +148,64 @@ async fn start_impl<G: GenServer>(args: G::Args, link: bool) -> Result<Pid, Erro
 /// Main entry point for a GenServer process.
 async fn gen_server_main<G: GenServer>(
     args: G::Args,
+    name: Option<Name>,
     init_tx: Option<tokio::sync::oneshot::Sender<Result<(), Error>>>,
 ) {
     let init_result = G::init(args).await;
 
     match init_result {
         Init::Ok(server) => {
+            if let Some(ref name) = name
+                && register_name(name, crate::current_pid()).is_err()
+            {
+                if let Some(tx) = init_tx {
+                    let _ = tx.send(Err(Error::AlreadyStarted));
+                }
+                return;
+            }
             if let Some(tx) = init_tx {
                 let _ = tx.send(Ok(()));
             }
             gen_server_loop(server).await;
+            if let Some(ref name) = name {
+                unregister_name(name);
+            }
         }
         Init::Continue(server, continue_arg) => {
+            if let Some(ref name) = name
+                && register_name(name, crate::current_pid()).is_err()
+            {
+                if let Some(tx) = init_tx {
+                    let _ = tx.send(Err(Error::AlreadyStarted));
+                }
+                return;
+            }
             if let Some(tx) = init_tx {
                 let _ = tx.send(Ok(()));
             }
             schedule_continue(&continue_arg);
             gen_server_loop(server).await;
+            if let Some(ref name) = name {
+                unregister_name(name);
+            }
         }
         Init::Timeout(server, duration) => {
+            if let Some(ref name) = name
+                && register_name(name, crate::current_pid()).is_err()
+            {
+                if let Some(tx) = init_tx {
+                    let _ = tx.send(Err(Error::AlreadyStarted));
+                }
+                return;
+            }
             if let Some(tx) = init_tx {
                 let _ = tx.send(Ok(()));
             }
             schedule_timeout(duration);
             gen_server_loop(server).await;
+            if let Some(ref name) = name {
+                unregister_name(name);
+            }
         }
         Init::Ignore => {
             if let Some(tx) = init_tx {

crates/ambitious/src/gen_server/server_ref.rs

@@ -1,11 +1,15 @@
 //! ServerRef - unified way to address a GenServer.
 
 use crate::core::Pid;
+use std::sync::Arc;
 
-/// A reference to a GenServer, either by PID or registered name.
+use super::via::ViaRegistry;
+
+/// A reference to a GenServer, either by PID, registered name, or via a
+/// pluggable registry.
 ///
 /// This allows GenServer client functions (`call`, `cast`, `stop`) to
-/// accept either a `Pid` or a name string.
+/// accept either a `Pid`, a name string, or a `Via` registry reference.
 ///
 /// # Examples
 ///
@@ -18,12 +22,13 @@ use crate::core::Pid;
 /// // By registered name
 /// let reply = call::<MyServer, _>("my_server", msg, timeout).await?;
 /// ```
-#[derive(Debug, Clone)]
 pub enum ServerRef {
     /// Reference by process ID.
     Pid(Pid),
     /// Reference by registered name.
     Name(String),
+    /// Reference via a pluggable registry.
+    Via(Arc<dyn ViaRegistry>),
 }
 
 impl ServerRef {
@@ -34,6 +39,27 @@ impl ServerRef {
         match self {
             ServerRef::Pid(pid) => Some(*pid),
             ServerRef::Name(name) => crate::whereis(name),
+            ServerRef::Via(via) => via.whereis_name(),
+        }
+    }
+}
+
+impl Clone for ServerRef {
+    fn clone(&self) -> Self {
+        match self {
+            ServerRef::Pid(pid) => ServerRef::Pid(*pid),
+            ServerRef::Name(name) => ServerRef::Name(name.clone()),
+            ServerRef::Via(via) => ServerRef::Via(Arc::clone(via)),
+        }
+    }
+}
+
+impl std::fmt::Debug for ServerRef {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            ServerRef::Pid(pid) => f.debug_tuple("Pid").field(pid).finish(),
+            ServerRef::Name(name) => f.debug_tuple("Name").field(name).finish(),
+            ServerRef::Via(_) => f.debug_tuple("Via").field(&"...").finish(),
         }
     }
 }
@@ -56,11 +82,18 @@ impl From<String> for ServerRef {
     }
 }
 
+impl From<Arc<dyn ViaRegistry>> for ServerRef {
+    fn from(via: Arc<dyn ViaRegistry>) -> Self {
+        ServerRef::Via(via)
+    }
+}
+
 impl std::fmt::Display for ServerRef {
     fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
         match self {
             ServerRef::Pid(pid) => write!(f, "{:?}", pid),
             ServerRef::Name(name) => write!(f, "{}", name),
+            ServerRef::Via(_) => write!(f, "<via>"),
         }
     }
 }