gorun

gorun

gorun is a Go package that provides a simple interface to run, monitor, and stop external programs, capturing their output and handling graceful shutdowns.

Usage

Installation

go get github.com/cdvelop/gorun

Example

package main

import (
    "os"
    "github.com/cdvelop/gorun"
)

func main() {
    config := &gorun.GoRunConfig{
        ExecProgramPath: "your_program",
        RunArguments:    func() []string { return []string{"--flag"} },
        ExitChan:        make(chan bool),
        Logger:          os.Stdout,
    }

    runner := gorun.New(config)

    // Start the program
    if err := runner.RunProgram(); err != nil {
        panic(err)
    }

    // ... do other work ...

    // Stop the program gracefully
    if err := runner.StopProgram(); err != nil {
        panic(err)
    }
}

API

type GoRunConfig

Configuration for running an external program.

• ExecProgramPath string: Path to the executable.
• RunArguments func() []string: Function returning the arguments to pass.
• ExitChan chan bool: Channel to signal exit.
• Logger io.Writer: Where to write program output.
• KillAllOnStop bool: If true, kills all instances of the executable when stopping.

func New(config *GoRunConfig) *GoRun

Creates a new runner instance.

func (g *GoRun) RunProgram() error

Runs the configured program and captures its output. If a program is already running, it stops the previous one first. If KillAllOnStop is enabled, it will also kill all other instances of the same executable.

func (g *GoRun) StopProgram() error

Stops the running program gracefully. If KillAllOnStop is enabled, it will also kill all other instances of the same executable.

func (g *GoRun) StopProgramAndCleanup(killAll bool) error

Stops the running program and optionally kills all instances of the same executable by name.

func KillAllByName(executableName string) error

Kills all running processes that match the given executable name. This is useful for cleanup when multiple instances might be running. Works cross-platform (Linux, Windows, macOS).

New Cleanup Features

Starting from this version, gorun includes enhanced cleanup capabilities to handle scenarios where multiple instances of the same program might be running:

Automatic Cleanup

Set KillAllOnStop: true in your config to automatically kill all instances:

config := &gorun.GoRunConfig{
    ExecProgramPath: "./my-server",
    RunArguments:    func() []string { return []string{"--port", "8080"} },
    ExitChan:        make(chan bool),
    Logger:          os.Stdout,
    KillAllOnStop:   true, // Kill ALL instances when stopping
}

Manual Cleanup

For explicit control over cleanup:

// Kill all instances manually
if err := gorun.KillAllByName("my-server"); err != nil {
    log.Printf("Cleanup failed: %v", err)
}

// Or use the method with explicit control
if err := runner.StopProgramAndCleanup(true); err != nil {
    log.Printf("Stop and cleanup failed: %v", err)
}

Use Cases

This is particularly useful for:

• Development servers: Ensure no orphaned processes when restarting
• Test cleanup: Prevent test pollution from previous runs
• CI/CD: Ensure clean deployment environments
• Multiple instances: When you need to ensure only one instance runs

For more details, see the GoDoc or the source