Thanks for writing this library! It seems helpful for my async code. I couldn't figure out how to handle this use case though: I have a nested subsystem, which will shut itself down on error. I want to retry from the top level in a loop. Something like

async fn top_subsystem(subsys: SubsystemHandle) -> Result<()> {
  let init = one_time_expensive_setup();
  loop {
    let s = cheap_setup();
    let nested = subsys.start("nested", nested_subsystem);
    nested.wait();
  }
}

async fn nested_subsystem(subsys: SubsystemHandle) -> Result<()> {
  ...
  // On error:
  subsys.request_shutdown();
}

How would I do the nested.wait() part?

Hi there! First off, thanks for this amazing project, it really helped simplifying my previous setup with handling shutdowns manually!

I tried to look for ways how people use this library in real world applications, but I couldn't really find much. I have a relatively simple question, so maybe you can guide me in the right direction:

Say I have 4 subsystems attached to the top level. Three of those need to send messages to the first one. Where would you create tx and how would you pass it down? At the moment I'm creating all of them in my main function and pass them into the new() function of every subsystem before calling run(subsys) on them. This looks a little bit like this, and I'm wondering if there's a cleaner solution (to be fair, I'm relatively new to rust):

#[tokio::main]
async fn main() -> Result<()> {
    Builder::from_env(Env::default().default_filter_or("debug")).init();

    let (foo_for_alpha_tx, foo_rx) = mpsc::channel(8);
    let foo_for_beta = foo_for_alpha.clone();
    let foo_for_gamma = foo_for_alpha.clone();

    Toplevel::new()
        .start("Alpha", |s| async move {
            Alpha::new(foo_for_alpha_tx).run(s).await
        })
        .start("Beta", |s| async move {
            Beta::new(foo_for_beta_tx).run(s).await
        })
        .start("Gamma", |s| async move {
            Beta::new(foo_for_gamma_tx).run(s).await
        })
        .start("Delta", |s| async move {
            Delta::new(foo_rx).run(s).await
        })
        .catch_signals()
        .handle_shutdown_requests(Duration::from_millis(1000))
        .await
}

In general, it'd be really nice to see a more complete example with subsystem intercommunication in the example directory I guess :)

Another question which popped into my mind, which I couldn't find an answer for: When a subsystem has nested subsystems and a shutdown is requested, do the nested subsystems shut down first before the parent, or is the order not guaranteed?

Thanks a lot for your time!

In my project I am not using anyhow and dont plan to - snafu implements something similar with Whatever if needed.

The problem is: I would love to use this project, but I have to use this dependency just for the callbacks.

IMO it would be nicer and easier to use a boxed error (Box<Error + Send + Sync>) - this introduces no extra dependency on anyhow and at the same time can contain all errors thrown at it.

I did get the chance to try out the beta version, and happy to say that it works great. Helped me clean up my code quite a bit. Feel free to close this issue!

One observation I will mention is that in most cases, I would like a newly started subsystem to select! on the parent's on_shutdown_requested so that it shuts down immediately on error, and this was causing quite a bit of boilerplate. I was able to address it with the following macro though

/// Start a nested subsystem that `select!`s on `subsys.on_shutdown_requested()` to stop automatically.
/// `subsystem_to_start` must have type `Future<Output=anyhow::Result<()>>`.
#[macro_export]
macro_rules! start {
    ($subsys:expr, $name:expr, $subsystem_to_start:expr) => {
        let subsys_clone = $subsys.clone();
        $subsys.start($name, move |_h: SubsystemHandle| async move {
            tokio::select! {
                r = $subsystem_to_start => r,
                _ = subsys_clone.on_shutdown_requested() => Ok::<(), anyhow::Error>(())
            }
        });
    };
}

Will leave it up to you on whether such a feature makes sense to be in the lib or not (in which case it can probably be another function on SubsystemHandle, rather than a macro).

Originally posted by @viveksjain in https://github.com/Finomnis/tokio-graceful-shutdown/issues/37#issuecomment-1147069424

This removes anyhow::Error from the future signatures. That way it's easier for people to integrate this crate without having to bring anyhow as a dependency.

I've updated all the examples.

Signed-off-by: David Calavera [email protected]

What would be involved in supporting such a feature? It would be cool if the parent subsystem was able to explicitly handle the child subsystem errors.

I'm trying to run the code examples on macOS but the program just hangs without any error indefinitely.

$ git clone [email protected]:Finomnis/tokio-graceful-shutdown.git
$ cd tokio-graceful-shutdown
$ cargo run --example 01_normal_shutdown
# builds successfully, then launches and hangs

$ rustc --version
rustc 1.64.0 (a55dd71d5 2022-09-19)
$ cargo --version
cargo 1.64.0 (387270bc7 2022-09-16)

macOS 12.5 (21G72)

Currently everything is a Box<dyn Error>, but as default template arguments for classes exist, we might make that a template argument with the default to Box<dyn Error>.

Reasoning is that this simplifies passing errors from subsystems to this crate and back to the user again, without the user having to resort to weird runtime matching to get the original error type back.

Hello! Do you think that this crate could be extended be used to restart failed tasks? That way we could have the same unit of abstraction (a "subsystem", which is a wrapper around a task) for both handling graceful shutdowns and recovering from failure (in case of panic this maybe means wrapping the future on catch_unwind before calling tokio::spawn, but there could be other ways to signal failure).

The reason I'm asking is that since tokio-graceful-shutdown is in charge of spawning the tasks, I can't have another crate (say, an hypothetical tokio-restart) fulfill this role. Any code that wanted to do restarts would need to hook on some internals of tokio-graceful-shutdown. Moreover, if a task is failed and the policy was not to restart it, then during the graceful shutdown it shouldn't be terminated.

And well, if this is done, then Toplevel::start can't receive just a closure anymore; it must receive two (one for the spawned future, another that decides whether the task is restarted if it fails), or maybe define a trait with two methods and receive a trait object there; the default impl for the new method could be to just not restart anything.

To be more specific, increase compatibility with:

• Box<dyn std::error::Error>
• anyhow
• miette

This is based on PR https://github.com/Finomnis/tokio-graceful-shutdown/pull/16, contributed by calavera.

Hi, I've been reading through the codebase. It looks like SubsystemDescriptors hold Arc<SubsystemData>. And the SubsystemData holds the subsystem descriptors (without an Arc). Doesn't this mean that even if the parent subsystem is dropped, there will be a cyclic reference between a SubsystemDescriptor and a SubsystemData? So neither gets dropped and the memory is leaked