proc

func Monitor ¶ added in v0.3.0

func Monitor(ctx context.Context, cmd *exec.Cmd, interval time.Duration) (<-chan Metrics, error)

Monitor polls the resource usage of cmd.Process at the given interval and sends each Metrics snapshot to the returned channel.

Monitor returns immediately. The sampling goroutine runs until:

• ctx is cancelled, or
• the channel's consumer stops reading (the channel is unbuffered).

The returned channel is closed when monitoring stops. Monitor returns an error only if the process has not been started yet (cmd.Process == nil).

Example:

cmd := proc.NewCmd(ctx, "worker", "--config", "prod.yaml")
if err := proc.Start(cmd); err != nil {
    log.Fatal(err)
}
ch, err := proc.Monitor(ctx, cmd, time.Second)
if err != nil {
    log.Fatal(err)
}
for m := range ch {
    fmt.Printf("pid=%d cpu=%.1f%% mem=%d KB\n", m.PID, m.CPUPercent, m.MemRSS/1024)
}

func NewCmd ¶ added in v0.2.0

func NewCmd(ctx context.Context, name string, args ...string) *exec.Cmd

NewCmd creates an *exec.Cmd pre-configured with context-linked cancellation (exec.CommandContext semantics). It is the recommended entry point when the caller holds a context, replacing the error-prone two-step pattern:

// before
cmd := exec.CommandContext(ctx, name, args...)
err := proc.Start(cmd)

// after
cmd := proc.NewCmd(ctx, name, args...)
err := proc.Start(cmd)

NewCmd does NOT call Start. The caller must still call proc.Start(cmd) to apply platform hygiene attributes (Pdeathsig on Linux, Job Objects on Windows) and launch the process. This separation allows configuring Stdout, Stdin, Env, Dir, etc. before starting.

package main

import (
	"context"
	"fmt"
	"time"

	"github.com/aretw0/procio/proc"
)

func main() {
	ctx, cancel := context.WithTimeout(context.Background(), 100*time.Millisecond)
	defer cancel()

	// NewCmd combines exec.CommandContext with automatic platform hygiene.
	// It is the recommended entry point: no need to import os/exec directly.
	cmd := proc.NewCmd(ctx, "sleep", "1")
	if err := proc.Start(cmd); err != nil {
		fmt.Println("Error starting process:", err)
		return
	}

	// Wait for process to finish or context to be cancelled.
	_ = cmd.Wait()
}

func Start ¶

func Start(cmd *exec.Cmd) error

Start starts the specified command but ensures that the child process is killed if the parent process (this process) dies.

On Linux, it uses SysProcAttr.Pdeathsig (SIGKILL). On Windows, it uses Job Objects (JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE).

On other platforms, it falls back to cmd.Start() and logs a warning, unless StrictMode is set to true, in which case it returns an error.

This is a safer alternative to cmd.Start() for long-running child processes.

package main

import (
	"context"
	"fmt"
	"os/exec"
	"time"

	"github.com/aretw0/procio/proc"
)

func main() {
	ctx, cancel := context.WithTimeout(context.Background(), 100*time.Millisecond)
	defer cancel()

	// Start a process. proc.Start wraps the standard exec.Cmd to provide
	// platform-specific guarantees (Job Objects on Windows, Pdeathsig on Linux)
	// that ensure child processes are terminated when the parent process exits.
	cmd := exec.CommandContext(ctx, "sleep", "1")

	// Start the process with hygiene guarantees.
	if err := proc.Start(cmd); err != nil {
		fmt.Println("Error starting process:", err)
		return
	}

	// Wait for process to finish or context to be cancelled.
	_ = cmd.Wait()
}