process

Documentation

Overview

Package process provides a helper for running and managing a subprocess.

It is intended for internal use by buildkite-agent only.

Index

• Variables
• func Cat(path string) (string, error)
• func FormatCommand(command string, args []string) string
• func GetPgid(pid int) (int, error)
• func Run(l logger.Logger, command string, arg ...string) (string, error)
• func SignalString(s syscall.Signal) string
• func StartPTY(c *exec.Cmd) (*os.File, error)
• type Buffer
  • func (l *Buffer) Close() error
  • func (l *Buffer) ReadAndTruncate() []byte
  • func (l *Buffer) Write(b []byte) (int, error)
• type Config
• type Process
  • func New(l logger.Logger, c Config) *Process
  • func (p *Process) Done() <-chan struct{}
  • func (p *Process) Interrupt() error
  • func (p *Process) Pid() int
  • func (p *Process) Run(ctx context.Context) error
  • func (p *Process) Started() <-chan struct{}
  • func (p *Process) Terminate() error
  • func (p *Process) WaitResult() error
  • func (p *Process) WaitStatus() WaitStatus
• type Scanner
  • func NewScanner(l logger.Logger) *Scanner
  • func (s *Scanner) ScanLines(r io.Reader, f func(line string)) error
• type Signal
  • func ParseSignal(sig string) (Signal, error)
  • func (s Signal) String() string
• type Timestamper
  • func NewTimestamper(w io.Writer, f func(t time.Time) string, timeout time.Duration) *Timestamper
  • func (p *Timestamper) Write(data []byte) (n int, err error)
• type WaitStatus

Variables

var ErrNotWaitStatus = errors.New(
	"unimplemented for systems where exec.ExitError.Sys() is not syscall.WaitStatus",
)

Functions

func Cat

func Cat(path string) (string, error)

Replicates how the command line tool `cat` works, but is more verbose about what it does

func FormatCommand

func FormatCommand(command string, args []string) string

FormatCommand formats a command amd arguments for human reading

func GetPgid

func GetPgid(pid int) (int, error)

func Run

func Run(l logger.Logger, command string, arg ...string) (string, error)

func SignalString

func SignalString(s syscall.Signal) string

SignalString returns the name of the given signal. For example, SignalString(syscall.Signal(15)) // "SIGTERM"

func StartPTY

func StartPTY(c *exec.Cmd) (*os.File, error)

Types

type Buffer

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

Buffer implements a concurrent-safe output buffer for processes.

func (*Buffer) Close

func (l *Buffer) Close() error

Close closes the buffer. Further writes will return io.ErrClosedPipe.

func (*Buffer) ReadAndTruncate

func (l *Buffer) ReadAndTruncate() []byte

ReadAndTruncate reads the unread contents of the buffer, and then truncates (empties) the buffer.

func (*Buffer) Write

func (l *Buffer) Write(b []byte) (int, error)

Write appends data to the buffer. If the buffer is closed, it returns io.ErrClosedPipe.

type Config

type Config struct {
	PTY               bool
	Timestamp         bool
	Path              string
	Args              []string
	Env               []string
	Stdin             io.Reader
	Stdout            io.Writer
	Stderr            io.Writer
	Dir               string
	InterruptSignal   Signal
	SignalGracePeriod time.Duration
}

Configuration for a Process

type Process

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

Process is an operating system level process

func New

func New(l logger.Logger, c Config) *Process

New returns a new instance of Process

func (*Process) Done

func (p *Process) Done() <-chan struct{}

Done returns a channel that is closed when the process finishes

func (*Process) Interrupt

func (p *Process) Interrupt() error

Interrupt the process on platforms that support it, terminate otherwise

func (*Process) Pid

func (p *Process) Pid() int

Pid is the pid of the running process

func (*Process) Run

func (p *Process) Run(ctx context.Context) error

Run the command and block until it finishes

func (*Process) Started

func (p *Process) Started() <-chan struct{}

Started returns a channel that is closed when the process is started

func (*Process) Terminate

func (p *Process) Terminate() error

Terminate the process

func (*Process) WaitResult

func (p *Process) WaitResult() error

WaitResult returns the raw error returned by Wait()

func (*Process) WaitStatus

func (p *Process) WaitStatus() WaitStatus

WaitStatus returns the status of the Wait() call

type Scanner

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

func NewScanner

func NewScanner(l logger.Logger) *Scanner

func (*Scanner) ScanLines

func (s *Scanner) ScanLines(r io.Reader, f func(line string)) error

type Signal

type Signal int

const (
	SIGHUP  Signal = 1
	SIGINT  Signal = 2
	SIGQUIT Signal = 3
	SIGUSR1 Signal = 10
	SIGUSR2 Signal = 12
	SIGTERM Signal = 15
)

func ParseSignal

func ParseSignal(sig string) (Signal, error)

func (Signal) String

func (s Signal) String() string

type Timestamper

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

Timestamper inserts timestamps generated by a callback at the start of each line, and inside lines when the line is...printed...very...slowly.

func NewTimestamper

func NewTimestamper(w io.Writer, f func(t time.Time) string, timeout time.Duration) *Timestamper

NewTimestamper sets up a Timestamper outputting to an io.Writer w. Timestamps are formatted with f, and non-prefix timestamps are inserted on writes that occur after timeout (duration since the previous timestamp).

func (*Timestamper) Write

func (p *Timestamper) Write(data []byte) (n int, err error)

Write writes the given data, plus any additional timestamps necessary, to the Timestamper's output. Timestamps are written at the start of each line, and possibly again within lines that are written incrementally over a long period of time.

type WaitStatus

type WaitStatus interface {
	ExitStatus() int
	Signaled() bool
	Signal() syscall.Signal
}