process

README

sup/process

sup/process is a small adapter between os/exec.Cmd and sup.Actor. The caller creates and configures an ordinary standard-library command; the actor runs one fresh command for each execution attempt.

Usage

package main

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

	"github.com/webermarci/sup"
	"github.com/webermarci/sup/process"
)

func main() {
	worker := process.NewActor("worker", func(ctx context.Context) *exec.Cmd {
		cmd := exec.CommandContext(ctx, "./worker", "--serve")
		cmd.Dir = "/srv/worker"
		cmd.Env = append(os.Environ(), "LOG_LEVEL=info")
		cmd.Stdout = os.Stdout
		cmd.Stderr = os.Stderr
		return cmd
	})

	supervisor := sup.NewSupervisor("root", sup.Transient).AddActors(worker)

	if err := supervisor.Run(context.Background()); err != nil {
		fmt.Println("supervisor failed:", err)
	}
}

Contract

• The command function is called once per execution attempt and must return a fresh *os/exec.Cmd; commands cannot be reused.
• Use os/exec.CommandContext with the supplied context when cancellation should stop the process.
• All command configuration remains standard Go: stdin, output, environment, working directory, platform attributes, cancellation, and WaitDelay are configured directly on os/exec.Cmd.
• Context cancellation is a clean actor shutdown and makes Run return nil.
• Other command errors are returned to the supervisor.

Process restarts, restart delays, restart limits, logging, and application state belong to the supervisor or application rather than this package.

Documentation

Overview

Package process adapts standard-library os/exec commands to sup actors.

Getting started

Create a process Actor with a command factory, then place it under a sup Supervisor:

worker := process.NewActor("worker", func(ctx context.Context) *exec.Cmd {
	return exec.CommandContext(ctx, "./worker", "--serve")
})

supervisor := sup.NewSupervisor("root", sup.Transient).AddActors(worker)

The command factory is called once for every execution attempt and must return a fresh *exec.Cmd. Configure environment, working directory, output, and cancellation on that command using the standard library.

Use exec.CommandContext with the supplied context when cancellation should stop the process. Context cancellation is a clean actor shutdown and makes Run return nil. Other command errors are returned to the supervisor and are handled by its restart policy.

See the package README and the package reference at https://pkg.go.dev/github.com/webermarci/sup/process for the complete API.

Index

• type Actor
  • func NewActor(id string, command func(context.Context) *exec.Cmd) *Actor
  • func (a *Actor) ID() string
  • func (a *Actor) Run(ctx context.Context) error

Examples

• Actor

Types

type Actor

type Actor struct {
	// contains filtered or unexported fields
}

Actor creates and runs an external command for each execution attempt. Process configuration and cancellation behavior belong to the command factory; the actor only adapts the command lifecycle to sup.Actor.

Example

package main

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

	"github.com/webermarci/sup"
	"github.com/webermarci/sup/process"
)

func main() {
	command := process.NewActor("hello", func(ctx context.Context) *exec.Cmd {
		cmd := exec.CommandContext(ctx, "sh", "-c", "printf 'hello from process actor\\n'")
		cmd.Stdout = os.Stdout
		return cmd
	})

	supervisor := sup.NewSupervisor("root", sup.Temporary).
		AddActors(command)
	if err := supervisor.Run(context.Background()); err != nil {
		panic(err)
	}
	fmt.Println("process finished")

}

Output:
hello from process actor
process finished

func NewActor

func NewActor(id string, command func(context.Context) *exec.Cmd) *Actor

NewActor creates a process actor with the given id and command factory. The factory must return a fresh command for every execution attempt. It should normally pass the supplied context to exec.CommandContext so cancellation stops the process.

func (*Actor) ID

func (a *Actor) ID() string

ID returns the actor id.

func (*Actor) Run

func (a *Actor) Run(ctx context.Context) error

Run creates and runs one command. Context cancellation is a clean actor shutdown and returns nil; other command errors are returned to the supervisor.