README
¶
procio
procio is a lightweight, standalone set of composable primitives for safe process lifecycle and interactive I/O in Go.
It provides three core primitives:
- proc: Leak-free process management (ensures child processes die when parent dies).
- termio: Interruptible terminal I/O (handling interrupts and safe terminal handles).
- scan: Robust input scanning with protection against "Fake EOF" signals on Windows.
Installation
go get github.com/aretw0/procio
Usage
starting a process safely
import "github.com/aretw0/procio/proc"
cmd := exec.Command("long-running-worker")
// Uses Pdeathsig (Linux) or Job Objects (Windows) to enforce cleanup
err := proc.Start(cmd)
Reading Input Robustly
import "github.com/aretw0/procio/scan"
scanner := scan.NewScanner(os.Stdin)
scanner.Start(ctx) // Handles transient interrupts
Enabling TTY Cancellation
For interactive CLIs that need Ctrl+C cancellation support:
import (
"context"
"github.com/aretw0/procio/scan"
)
ctx, cancel := context.WithCancel(context.Background())
defer cancel()
scanner := scan.NewScanner(os.Stdin,
scan.WithInterruptible(), // Enables context cancellation via Ctrl+C
scan.WithLineHandler(func(line string) {
fmt.Println("Got:", line)
}),
)
scanner.Start(ctx) // Returns when context is cancelled or EOF
Observability
procio is opinionated about specific mechanisms but unopinionated about logging/metrics.
You can inject your own observer:
import "github.com/aretw0/procio"
procio.SetObserver(myObserver)
Documentation
¶
Overview ¶
Package procio is the root package for robust process I/O and signaling primitives.
It provides a platform-agnostic way to handle process execution and terminal input with safety guarantees (like leak-free process termination using Job Objects on Windows and Pdeathsig on Linux).
Subpackages ¶
- proc: Process management and lifecycle guarantees.
- scan: Context-aware parsing of input streams (Scanner).
- termio: Terminal I/O utilities and interruptible readers.
Observability ¶
procio does not depend on any logging library. Instead, it exposes an Observer interface that you can implement to bridge logs and metrics to your preferred system.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var Version string
Functions ¶
func SetObserver ¶
func SetObserver(o Observer)
SetObserver configures the global observer for process events.
Types ¶
type Observer ¶
type Observer interface {
OnProcessStarted(pid int)
OnProcessFailed(err error)
OnIOError(op string, err error)
OnScanError(err error)
LogDebug(msg string, args ...any)
LogWarn(msg string, args ...any)
LogError(msg string, args ...any)
}
Observer allows external packages to plug in observability (logs, metrics) without coupling this module to specific implementations.
func GetObserver ¶
func GetObserver() Observer
GetObserver returns the current global observer. Useful for sub-packages to access the shared observer.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
examples
|
|
|
basic
command
|
|
|
composition
command
|
|
|
interruptible
command
|
|
|
observer
command
|
|
|
Package proc provides platform-agnostic process management with safety guarantees.
|
Package proc provides platform-agnostic process management with safety guarantees. |
|
Package scan provides a robust, context-aware command and line scanner.
|
Package scan provides a robust, context-aware command and line scanner. |
|
Package termio provides interruptible I/O primitives and terminal handling.
|
Package termio provides interruptible I/O primitives and terminal handling. |