ProcessManager

ProcessManager is a light-weight Tokio based supervisor for coordinating multiple long-running asynchronous tasks (called processes). It takes care of

• spawning all registered processes,
• forwarding reload / shutdown commands,
• propagating errors,
• initiating a graceful shutdown of the whole tree once any process fails,
• and optionally cleaning up completed children to avoid memory leaks.

The crate is completely runtime-agnostic except for its dependency on Tokio tasks behind the scenes; you are free to use any async code in your own processes.

Table of Contents

1. Features
2. Installation
3. Quick-Start
4. Built-in Helpers
5. Examples
6. High-Level Architecture
7. Crate Features
8. License

Features

Installation

Add the dependency to your Cargo.toml:

[dependencies]
processmanager = "0"

Optional features are listed below.

Quick-Start

A minimal program that runs two workers for three seconds and then shuts down gracefully:

use processmanager::*;
use std::{sync::Arc, time::Duration};
use tokio::time::{interval, sleep};

struct Worker {
    id: usize,
    guard: Arc<RuntimeGuard>,
}

impl Worker {
    fn new(id: usize) -> Self {
        Self { id, guard: Arc::new(RuntimeGuard::default()) }
    }
}

impl Runnable for Worker {
    fn process_start(&self) -> ProcFuture<'_> {
        let id = self.id;
        let guard = self.guard.clone();

        Box::pin(async move {
            let ticker = guard.runtime_ticker().await;
            let mut beat = interval(Duration::from_secs(1));

            loop {
                match ticker.tick(beat.tick()).await {
                    ProcessOperation::Next(_) => println!("worker-{id}: heartbeat"),
                    ProcessOperation::Control(RuntimeControlMessage::Shutdown) => break,
                    _ => continue,
                }
            }
            Ok(())
        })
    }

    fn process_handle(&self) -> Arc<dyn ProcessControlHandler> {
        self.guard.handle()
    }
}

#[tokio::main]
async fn main() {
    let manager = ProcessManagerBuilder::default()
        .pre_insert(Worker::new(0))
        .pre_insert(Worker::new(1))
        .build();

    let handle = manager.process_handle();

    tokio::spawn(async move {
        manager.process_start().await.expect("manager error");
    });

    sleep(Duration::from_secs(3)).await;
    handle.shutdown().await;
}

Built-in Helpers

Enable SignalReceiver like this:

processmanager = { version = "0", features = ["signal"] }

Examples

Ready-to-run examples live in examples/ and can be launched with Cargo:

Feel free to copy or adapt the code for your own services.

High-Level Architecture

flowchart TD
    subgraph Supervisor
        Mgr(ProcessManager)
    end
    Mgr -->|spawn| Child1[Runnable #1]
    Mgr --> Child2[Runnable #2]
    Child1 -- control --> Mgr
    Child2 -- control --> Mgr
    ExtHandle(External Handle) -- shutdown / reload --> Mgr

• Every Runnable gets its own Tokio task.
• A ProcessControlHandler allows external code to shut down or reload a single process or the whole subtree.
• The first child that ends in Err(_) terminates the entire supervisor.

Crate Features

Pick one of tracing or log to avoid duplicate output.

License

Licensed under either of

• Apache License, Version 2.0
• MIT license

at your option.