Struct Supervisor 

pub struct Supervisor { /* private fields */ }

A supervisor is a process which supervises other processes, which we refer to as child processes. Supervisors are used to build a hierarchical process structure called a supervision tree. Supervision trees provide fault-tolerance and encapsulate how our applications start and shutdown.

Implementations

impl Supervisor

pub const fn new() -> Self

Constructs a new instance of Supervisor with no children.

pub fn with_children<T: IntoIterator<Item = ChildSpec>>(children: T) -> Self

Constructs a new instance of Supervisor with the given children.

Examples found in repository

examples/supervisor.rs (line 38)

    async fn start(&self) -> Result<Pid, ExitReason> {
        // Spawn two instances of `MyServer` with their own unique ids.
        let children = [
            MyServer::new().child_spec().id("server1"),
            MyServer::new().child_spec().id("server2"),
        ];

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

examples/registry.rs (line 77)

    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 add_child(self, child: ChildSpec) -> Self

Adds a child to this Supervisor.

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

Builds a child specification for this Supervisor process.

pub const fn strategy(self, strategy: SupervisionStrategy) -> Self

Sets the supervision strategy for the Supervisor.

Examples found in repository

examples/supervisor.rs (line 39)

    async fn start(&self) -> Result<Pid, ExitReason> {
        // Spawn two instances of `MyServer` with their own unique ids.
        let children = [
            MyServer::new().child_spec().id("server1"),
            MyServer::new().child_spec().id("server2"),
        ];

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

examples/registry.rs (line 78)

    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 const fn auto_shutdown(self, auto_shutdown: AutoShutdown) -> Self

Sets the behavior to use when a significant process exits.

pub const fn max_restarts(self, max_restarts: usize) -> Self

Sets the maximum number of restarts allowed in a time frame.

Defaults to 3.

pub const fn max_duration(self, max_duration: Duration) -> Self

Sets the time frame in which max_restarts applies.

Defaults to 5s.

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

Creates a supervisor process not apart of a supervision tree.

This will not return until all of the child processes have been started.

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

Creates a supervisor process as part of a supervision tree.

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

This will not return until all of the child processes have been started.

Examples found in repository

examples/supervisor.rs (line 40)

    async fn start(&self) -> Result<Pid, ExitReason> {
        // Spawn two instances of `MyServer` with their own unique ids.
        let children = [
            MyServer::new().child_spec().id("server1"),
            MyServer::new().child_spec().id("server2"),
        ];

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

examples/registry.rs (line 79)

    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 count_children<T: Into<Dest>>( supervisor: T, ) -> Result<SupervisorCounts, SupervisorError>

Returns SupervisorCounts containing the counts for each of the different child specifications.

pub async fn start_child<T: Into<Dest>>( supervisor: T, child: ChildSpec, ) -> Result<Option<Pid>, SupervisorError>

Adds the child specification to the Supervisor and starts that child.

pub async fn terminate_child<T: Into<Dest>, I: Into<String>>( supervisor: T, child_id: I, ) -> Result<(), SupervisorError>

Terminates the given child identified by child_id.

The process is terminated, if there’s one. The child specification is kept unless the child is temporary.

A non-temporary child process may later be restarted by the Supervisor.

The child process can also be restarted explicitly by calling restart_child. Use delete_child to remove the child specification.

pub async fn restart_child<T: Into<Dest>, I: Into<String>>( supervisor: T, child_id: I, ) -> Result<Option<Pid>, SupervisorError>

Restarts a child identified by child_id.

The child specification must exist and the corresponding child process must not be running.

Note that for temporary children, the child specification is automatically deleted when the child terminates, and thus it is not possible to restart such children.

pub async fn delete_child<T: Into<Dest>, I: Into<String>>( supervisor: T, child_id: I, ) -> Result<(), SupervisorError>

Deletes the child specification identified by child_id.

The corrosponding child process must not be running, use terminate_child to terminate it if it’s running.

pub async fn which_children<T: Into<Dest>>( supervisor: T, ) -> Result<Vec<SupervisorChildInfo>, SupervisorError>

Returns a list with information about all children of the given Supervisor.

Trait Implementations

impl Clone for Supervisor

fn clone(&self) -> Supervisor

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Default for Supervisor

fn default() -> Self

Returns the “default value” for a type.

impl GenServer for Supervisor

type Message = SupervisorMessage

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.