graceproc

Go process supervision with graceful cancellation and descendant cleanup on Linux, macOS and Windows. Run accepts an os/exec.Cmd and a signal channel; RunWithGrace lets the caller choose the cancellation grace period.

Setup

Add the release to your Go module:

go get github.com/latticebuild/graceproc@v0.1.0

Bazel consumers import the same Go release through Gazelle's go_deps extension and depend on @com_github_latticebuild_graceproc//:graceproc. See the Bazel setup and external caller.

Usage

package main

import (
    "fmt"
    "os"
    "os/exec"
    "os/signal"

    "github.com/latticebuild/graceproc"
)

func main() {
    signals := make(chan os.Signal, 2)
    signal.Notify(signals, graceproc.Signals()...)
    cmd := exec.Command("node", "server.mjs")
    cmd.Stdin, cmd.Stdout, cmd.Stderr = os.Stdin, os.Stdout, os.Stderr
    code, err := graceproc.Run(cmd, signals)
    signal.Stop(signals)
    if err != nil {
        fmt.Fprintln(os.Stderr, err)
        if code == 0 {
            code = 1
        }
    }
    os.Exit(code)
}

Supervision returns after bounded cleanup, including when the parent exits normally. Unix ownership is a process group; descendants that create another group or session need cleanup by the tool that created them. Windows ownership is a Job Object assigned before the child starts running. Cleanup failures remain errors even if the child exits successfully.

Repository map

Area	Location
Public package	graceproc.go
Process tests	graceproc_test.go
Development guide	docs/development.md

Documentation and examples

See the generated API reference and runnable examples.

Development

Install Mise, then prepare this checkout:

mise trust
mise run bootstrap
hk validate
hk test
hk check --all --slow
bazel build //:artifacts
bazel test //:test

Tools and dependency versions are pinned in mise.toml and MODULE.bazel. CI runs these gates on native Linux, macOS and Windows runners. Repositories with a race suite also run it on Linux and macOS. See docs/development.md for owning checks and platform constraints, and ARCHITECTURE.md for implementation decisions.

License

Apache License 2.0.

Sponsor us · Discuss questions and ideas

Pull requests are limited to repository collaborators. Use Discussions for bugs, feature requests and support. Changes merge as squash commits.