process

README

process Package

Documentation

Index

• func Batch(h host.Host, batch []Program, options ...Options) (done chan struct{}, err error)
• func Daemon(writepid io.WriteCloser, processArgs func([]string, ...string) []string, ...) (err error)
• func GetPID(h host.Host, binaryPrefix string, ...) (pid int, err error)
• func RemoveArgs(in []string, remove ...string) (out []string)
• func Start(h host.Host, program Program, options ...Options) (pid int, err error)
• type Options
  • func ExpandArgs() Options
  • func ExpandEnv() Options
  • func LookupTable(table map[string]string) Options
• type Program

Functions

func Batch

func Batch(h host.Host, batch []Program, options ...Options) (done chan struct{}, err error)

Batch executes the slice of Program entries using Start. If any stage returns err then Batch returns immediately. Set IgnoreErr in Program to not return errors for each stage. If any stage has Restart set and it is supported then a reaper is run and the done channel returned.

func Daemon

func Daemon(writepid io.WriteCloser, processArgs func([]string, ...string) []string, args ...string) (err error)

Daemon backgrounds the current process by re-executing the existing binary (as found by os.Executable, so may there is a small window while the referenced binary can change). The function passed as processArgs is called with any further arguments passed to it as parameters and can be used to remove flags that triggered the daemonisation in the first place. A helper function - RemoveArgs - is available to do this.

If successful the function never returns and the child process PID is written to writepid, if not nil. Remember to only open the file inside the test for daemon mode in the caller, otherwise on re-execution the file will be re-opened and overwrite the one from the parent. writepid is closed in the parent.

On failure the function does return with an error.

process.Daemon(os.Stdout, process.RemoveArgs, "-D", "--daemon")

func GetPID

func GetPID(h host.Host, binaryPrefix string, customCheckFunc func(arg any, cmdline ...[]byte) bool, checkarg any, args ...string) (pid int, err error)

GetPID returns the PID of the process started with binary name and all args (in any order) on host h. If not found then an err of os.ErrProcessDone is returned.

checkfn() is a custom function to validate the args against the each process found and checkargs is passed to the function as a parameter. If the function returns true then the process is a match.

walk the /proc directory (local or remote) and find the matching pid. This is subject to races, but not much we can do

TODO: add support for windows hosts - the lookups are based on the host h and not the local system

TODO: cache /proc entries for a period, this is very likely to be used over and over in the same proc

func RemoveArgs

func RemoveArgs(in []string, remove ...string) (out []string)

RemoveArgs is a helper function for Daemon(). Daemon calls the function with os.Args[1;] and removes any arguments matching members of the slice `remove` and returns the result. Only bare arguments are removed and no pattern matching or adjacent values are removed. If this is required then pass your own function with the same signature.

func Start

func Start(h host.Host, program Program, options ...Options) (pid int, err error)

Start runs a process on host h. It is run detached in the background unless Foreground is true.

TODO: return error windows TODO: look at remote processes

Types

type Options

type Options func(*processOptions)

Options for Start and Batch

func ExpandArgs

func ExpandArgs() Options

ExpandArgs controls the expansion of the values in the Args slice. If this option is used then each element of the Args slice is passed to ExpandString with an lookup tables set using LookupTable().

func ExpandEnv

func ExpandEnv() Options

ExpandEnv controls the expansion of the values in the Env slice. If this option is used then each element of the Env slice is passed to ExpandString with an lookup tables set using LookupTable().

func LookupTable

func LookupTable(table map[string]string) Options

LookupTable adds a lookup map (string to string) to the set of lookup tables passed to ExpandString.

type Program

type Program struct {
	Executable string        `json:"executable,omitempty"` // Path to program, passed through exec.LookPath
	Username   string        `json:"username,omitempty"`   // The name of the user, if empty use current
	WorkingDir string        `json:"workingdir,omitempty"` // The working directory, defaults to home dir of user
	ErrLog     string        `json:"errlog,omitempty"`     // The name of the logfile, defaults to basename of program+".log" in Dir
	Args       []string      `json:"args,omitempty"`       // Args not including program
	Env        []string      `json:"env,omitempty"`        // Env as key=value pairs
	Foreground bool          `json:"foreground,omitempty"` // Run in foreground, to completion, return if result != 0
	Restart    bool          `json:"restart,omitempty"`    // restart on exit
	IgnoreErr  bool          `json:"ignoreerr,omitempty"`  // If true do not return err on failure
	Wait       time.Duration `json:"wait,omitempty"`       // period to wait after starting, default none
}

Program is a highly simplified representation of a program to manage with Start or Batch.

Args and Env can be either a comma delimited string, which is split by viper/mapstructure, or a slice of strings which is used as-is