gohup

README

GoHUP

GoHup allows you to run a long running command in a detached background process. It is not a daemon runner which monitors the status of the process restarting when necessary, GoHup only starts the process and returns the process id.

GoHup is similar to the Unix command nohup, except GoHup automatically creates a PID file and redirects log output to a file. You can use GoHup in your own applications, commands started with GoHup will continue to run after the application using the library has exited.

Usage

To create and start a new process create a new instance of gohup.LocalProcess and call the Start method with the process options.

The following exanple will start the command tail in the background and return the pid and the pidfile containing the pid.

lp := &gohup.LocalProcess{}
o := gohup.Options{
	Path: "/usr/bin/tail",
	Args: []string{
		"-f",
		"/dev/null",
	},
  Logfile: "./process.log",
}

pid, pidfile, err := lp.Start(o)
if err != nil {
	panic(err)
}

fmt.Printf("Started PID: %d, PID file: %s\n", pid, pidfile)

To query the status of a process, you can use the QueryStatus method passing the location of the pidfile. QueryStatus will return a string, gohup.StatusRunning or gohup.StatusStopped depending on the state of the process.

s, err := lp.QueryStatus(pidfile)
if err != nil {
	panic(err)
}

fmt.Println("Status:", s)

To stop a backgrounded process you can call the Stop method passing the location of a pidfile.

GoHup removes the pidfile if Stop is successful.

fmt.Println("Stopping process")
err = lp.Stop(pidfile)
if err != nil {
	panic(err)
}

Documentation

Index

• func Kill(pid *os.Process)
• func SetSysProcAttr() *syscall.SysProcAttr
• type LocalProcess
  • func (l *LocalProcess) QueryStatus(pidfile string) (Status, error)
  • func (l *LocalProcess) Start(options Options) (int, string, error)
  • func (l *LocalProcess) Stop(pidfile string) error
• type Options
• type Process
• type Status

Functions

func Kill

func Kill(pid *os.Process)

func SetSysProcAttr

func SetSysProcAttr() *syscall.SysProcAttr

Types

type LocalProcess

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

LocalProcess is the implementation of the Process interface.

func (*LocalProcess) QueryStatus

func (l *LocalProcess) QueryStatus(pidfile string) (Status, error)

QueryStatus of the backgrounded process referenced by the PID in the given file.

If the process is not running StatusStopped, and a nil error will be returned. If the process is running StatusRunning, and a nil error will be returned. If it is not possible to query the status of the process or if the pidfile is not readable. StatusError, and an error will be returned.

func (*LocalProcess) Start

func (l *LocalProcess) Start(options Options) (int, string, error)

Start returns the process ID and the pidfile for the running process. If a process can not be started then an error will be returned.

func (*LocalProcess) Stop

func (l *LocalProcess) Stop(pidfile string) error

Stop the process referenced by the PID in the given file.

type Options

type Options struct {
	// Path of the process to start
	Path string
	// Arguments to pass when starting the process
	Args []string
	// Environments to pass when starting the process
	Env []string
	// Directory to start the process in, default is the current directory
	Dir string
	// File to write the running process ID to, if blank a temporary file
	// will be created.
	Pidfile string
	// File to write output from the started command to, if blank logs
	// will be disgarded
	Logfile string
}

Options to be used when starting a process

type Process

type Process interface {
	// Start a process in the background
	Start(options Options) (int, string, error)
	// Stop the current running process
	Stop(pidfile string, signal syscall.Signal) error
	// Return the status of the currently running process
	QueryStatus(pidfile string) (Status, error)
}

Process defines an interface which defines methods for managing a child process.

type Status

type Status string

Status of the process

const StatusError Status = "StatusError"

StatusError is returned when it is not possible to determine the status of a process

const StatusNotFound Status = "StatusNotFound"

StatusNotFound is returned when the pid does not exist

const StatusRunning Status = "StatusRunning"

StatusRunning is returned when the process is Running

const StatusStopped Status = "StatusStopped"

StatusStopped is returned when the process is Stopped