Struct Registry 

pub struct Registry { /* private fields */ }

Provides a centralized ‘registry’ of processes using any value as a key.

A registry is designed to only support a single type of Process or GenServer, you should use multiple if necessary.

Implementations

impl Registry

pub fn new<T: Into<String>>(name: T) -> Self

Constructs a new local Registry with the given name.

Names must be unique on a per-node basis.

Examples found in repository

examples/registry.rs (line 61)

    async fn start(&self) -> Result<Pid, ExitReason> {
        // Spawn a registry that will take care of registering 'MySpace'.
        let children = [
            Registry::new("space-registry")
                .with_start(|key| {
                    let RegistryKey::String(id) = key else {
                        panic!()
                    };

                    MySpace::new(id).start_link(GenServerOptions::new())
                })
                .with_shutdown(Shutdown::Infinity)
                .child_spec(RegistryOptions::new())
                .id("space-registry"),
            ChildSpec::new("test-registry")
                .start(move || async { Ok(Process::spawn(test_registry())) }),
        ];

        // Restart only the terminated child.
        Supervisor::with_children(children)
            .strategy(SupervisionStrategy::OneForOne)
            .start_link(SupervisorOptions::new())
            .await
    }

pub fn with_start<T, F>(self, start: T) -> Self

where T: Fn(RegistryKey) -> F + Send + Sync + 'static, F: Future<Output = Result<Pid, ExitReason>> + Send + Sync + 'static,

Assigns a start routine for the registry to be able to dynamically spawn processes.

Must return a future that resolves to Result<Pid, ExitReason>.

Examples found in repository

examples/registry.rs (lines 62-68)

    async fn start(&self) -> Result<Pid, ExitReason> {
        // Spawn a registry that will take care of registering 'MySpace'.
        let children = [
            Registry::new("space-registry")
                .with_start(|key| {
                    let RegistryKey::String(id) = key else {
                        panic!()
                    };

                    MySpace::new(id).start_link(GenServerOptions::new())
                })
                .with_shutdown(Shutdown::Infinity)
                .child_spec(RegistryOptions::new())
                .id("space-registry"),
            ChildSpec::new("test-registry")
                .start(move || async { Ok(Process::spawn(test_registry())) }),
        ];

        // Restart only the terminated child.
        Supervisor::with_children(children)
            .strategy(SupervisionStrategy::OneForOne)
            .start_link(SupervisorOptions::new())
            .await
    }

pub fn with_shutdown(self, shutdown: Shutdown) -> Self

Sets the method used to shutdown any registered processes once when the Registry is terminated.

Examples found in repository

examples/registry.rs (line 69)

    async fn start(&self) -> Result<Pid, ExitReason> {
        // Spawn a registry that will take care of registering 'MySpace'.
        let children = [
            Registry::new("space-registry")
                .with_start(|key| {
                    let RegistryKey::String(id) = key else {
                        panic!()
                    };

                    MySpace::new(id).start_link(GenServerOptions::new())
                })
                .with_shutdown(Shutdown::Infinity)
                .child_spec(RegistryOptions::new())
                .id("space-registry"),
            ChildSpec::new("test-registry")
                .start(move || async { Ok(Process::spawn(test_registry())) }),
        ];

        // Restart only the terminated child.
        Supervisor::with_children(children)
            .strategy(SupervisionStrategy::OneForOne)
            .start_link(SupervisorOptions::new())
            .await
    }

pub async fn lookup<T: Into<Dest>, N: Into<RegistryKey>>( registry: T, key: N, timeout: Option<Duration>, ) -> Result<Option<Pid>, RegistryError>

Looks up a running process.

If the registry is local, this will just query the table without hitting the registry process.

Examples found in repository

examples/registry.rs (line 31)

async fn test_registry() {
    Registry::start_process("space-registry", "my awesome space id", None)
        .await
        .expect("Failed to start process");

    Registry::start_process("space-registry", "my lame space id", None)
        .await
        .expect("Failed to start process");

    let pid = Registry::lookup("space-registry", "my awesome space id", None)
        .await
        .expect("Failed to lookup process");

    tracing::info!("Looked up space process: {:?}", pid);

    let count = Registry::count("space-registry", None)
        .await
        .expect("Failed to count processes");

    tracing::info!("Count of registered processes: {:?}", count);

    let list = Registry::list("space-registry", None)
        .await
        .expect("Failed to list processes");

    tracing::info!("List of registered processes: {:?}", list);
}

pub async fn lookup_or_start<T: Into<Dest>, N: Into<RegistryKey>>( registry: T, key: N, timeout: Option<Duration>, ) -> Result<Pid, RegistryError>

Attempts to lookup a running process.

If the process isn’t currently running, it is spawned and passed the key.

pub async fn start_process<T: Into<Dest>, N: Into<RegistryKey>>( registry: T, key: N, timeout: Option<Duration>, ) -> Result<Pid, RegistryError>

Attempts to start a process.

If the process is already running, an error is returned.

Examples found in repository

examples/registry.rs (line 23)

async fn test_registry() {
    Registry::start_process("space-registry", "my awesome space id", None)
        .await
        .expect("Failed to start process");

    Registry::start_process("space-registry", "my lame space id", None)
        .await
        .expect("Failed to start process");

    let pid = Registry::lookup("space-registry", "my awesome space id", None)
        .await
        .expect("Failed to lookup process");

    tracing::info!("Looked up space process: {:?}", pid);

    let count = Registry::count("space-registry", None)
        .await
        .expect("Failed to count processes");

    tracing::info!("Count of registered processes: {:?}", count);

    let list = Registry::list("space-registry", None)
        .await
        .expect("Failed to list processes");

    tracing::info!("List of registered processes: {:?}", list);
}

pub async fn stop_process<T: Into<Dest>, N: Into<RegistryKey>>( registry: T, key: N, timeout: Option<Duration>, ) -> Result<(), RegistryError>

Stops a process registered in the given registry with the given key.

If the process is trapping exits, it will still run, but be unregistered from this registry.

If the process is not registered an error is returned.

pub async fn count<T: Into<Dest>>( registry: T, timeout: Option<Duration>, ) -> Result<usize, RegistryError>

Returns the number of registered processes for the given registry.

Examples found in repository

examples/registry.rs (line 37)

async fn test_registry() {
    Registry::start_process("space-registry", "my awesome space id", None)
        .await
        .expect("Failed to start process");

    Registry::start_process("space-registry", "my lame space id", None)
        .await
        .expect("Failed to start process");

    let pid = Registry::lookup("space-registry", "my awesome space id", None)
        .await
        .expect("Failed to lookup process");

    tracing::info!("Looked up space process: {:?}", pid);

    let count = Registry::count("space-registry", None)
        .await
        .expect("Failed to count processes");

    tracing::info!("Count of registered processes: {:?}", count);

    let list = Registry::list("space-registry", None)
        .await
        .expect("Failed to list processes");

    tracing::info!("List of registered processes: {:?}", list);
}

pub async fn list<T: Into<Dest>>( registry: T, timeout: Option<Duration>, ) -> Result<Vec<(RegistryKey, Pid)>, RegistryError>

Returns a list of every process registered to the given registry.

There is no ordering guarantee.

Examples found in repository

examples/registry.rs (line 43)

async fn test_registry() {
    Registry::start_process("space-registry", "my awesome space id", None)
        .await
        .expect("Failed to start process");

    Registry::start_process("space-registry", "my lame space id", None)
        .await
        .expect("Failed to start process");

    let pid = Registry::lookup("space-registry", "my awesome space id", None)
        .await
        .expect("Failed to lookup process");

    tracing::info!("Looked up space process: {:?}", pid);

    let count = Registry::count("space-registry", None)
        .await
        .expect("Failed to count processes");

    tracing::info!("Count of registered processes: {:?}", count);

    let list = Registry::list("space-registry", None)
        .await
        .expect("Failed to list processes");

    tracing::info!("List of registered processes: {:?}", list);
}

pub async fn remove<T: Into<Dest>, N: Into<RegistryKey>>( registry: T, key: N, timeout: Option<Duration>, ) -> Result<Option<Pid>, RegistryError>

Removes a process registered in the given registry with the given key.

The process will no longer be registered, but it will remain running if it was found.

pub async fn start(self, options: RegistryOptions) -> Result<Pid, ExitReason>

Create a registry proces not linked to a supervision tree.

pub async fn start_link( self, options: RegistryOptions, ) -> Result<Pid, ExitReason>

Creates a registry process as part of a supervision tree.

For example, this function ensures that the registry is linked to the calling process (its supervisor).

pub fn child_spec(self, options: RegistryOptions) -> ChildSpec

Builds a child specification for this Registry process.

Examples found in repository

examples/registry.rs (line 70)

    async fn start(&self) -> Result<Pid, ExitReason> {
        // Spawn a registry that will take care of registering 'MySpace'.
        let children = [
            Registry::new("space-registry")
                .with_start(|key| {
                    let RegistryKey::String(id) = key else {
                        panic!()
                    };

                    MySpace::new(id).start_link(GenServerOptions::new())
                })
                .with_shutdown(Shutdown::Infinity)
                .child_spec(RegistryOptions::new())
                .id("space-registry"),
            ChildSpec::new("test-registry")
                .start(move || async { Ok(Process::spawn(test_registry())) }),
        ];

        // Restart only the terminated child.
        Supervisor::with_children(children)
            .strategy(SupervisionStrategy::OneForOne)
            .start_link(SupervisorOptions::new())
            .await
    }

Trait Implementations

impl Clone for Registry

fn clone(&self) -> Registry

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Drop for Registry

fn drop(&mut self)

Executes the destructor for this type.

impl GenServer for Registry

type Message = RegistryMessage

The message type that this server will use.

async fn init(&mut self) -> Result<(), ExitReason>

Invoked when the server is started. start_link or start will block until it returns.

async fn terminate(&mut self, _reason: ExitReason)

Invoked when the server is about to exit. It should do any cleanup required.

async fn handle_cast( &mut self, message: Self::Message, ) -> Result<(), ExitReason>

Invoked to handle asynchronous cast messages.

async fn handle_call( &mut self, message: Self::Message, _from: From, ) -> Result<Option<Self::Message>, ExitReason>

Invoked to handle synchronous call messages. call will block until a reply is received (unless the call times out or nodes are disconnected).

async fn handle_info( &mut self, info: Message<Self::Message>, ) -> Result<(), ExitReason>

Invoked to handle all other messages.

fn start( self, options: GenServerOptions, ) -> impl Future<Output = Result<Pid, ExitReason>> + Send

Starts a GenServer process without links.

fn start_link( self, options: GenServerOptions, ) -> impl Future<Output = Result<Pid, ExitReason>> + Send

Starts a GenServer process linked to the current process.

fn stop<T: Into<Dest>>( server: T, reason: ExitReason, timeout: Option<Duration>, ) -> impl Future<Output = Result<(), ExitReason>>

Synchronously stops the server with the given reason.

fn cast<T: Into<Dests>>(servers: T, message: Self::Message)

Casts a request to the servers without waiting for a response.

fn cast_after<T: Into<Dests>>( servers: T, message: Self::Message, duration: Duration, ) -> Reference

Casts a request to the servers after the given duration without waiting for a response.

fn call<T: Into<Dest>>( server: T, message: Self::Message, timeout: Option<Duration>, ) -> impl Future<Output = Result<Self::Message, CallError>> + Send

Makes a synchronous call to the server and waits for it’s reply.

fn reply(from: From, message: Self::Message)

Replies to a client.