rwccmd

README

Docs

See https://godoc.org/github.com/problame/go-rwccmd

Documentation

Overview

rwcccmd provides rwccmd.Cmd, which starts a new process and exposes its stdout & stdin as a combined io.ReadWriteCloser.

Index

• Variables
• func ContextWithLog(ctx context.Context, log Logger) context.Context
• type Cmd
  • func CommandContext(ctx context.Context, bin string, args []string, env []string) (*Cmd, error)
  • func (c *Cmd) Close() (err error)
  • func (c *Cmd) CloseAtDeadline(deadline time.Time) error
  • func (c *Cmd) Kill() error
  • func (c *Cmd) Pid() int
  • func (c *Cmd) Read(out []byte) (n int, err error)
  • func (c *Cmd) Start() error
  • func (c *Cmd) WaitStatus() (ws syscall.WaitStatus, ok bool)
  • func (c *Cmd) Write(out []byte) (n int, err error)
• type Logger

Variables

var ErrDeadline = errors.New("deadline expired")

Functions

func ContextWithLog

func ContextWithLog(ctx context.Context, log Logger) context.Context

ContextWithLog adds a Logger log to ctx that will be called by rwccmd.Cmd. This is most useful for debugging.

Types

type Cmd

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

Cmd represents a spawned process for its entire lifecycle. Cmd is not concurrency-safe (Read and Write) must be serialized, but cancellation can happen asynchronously through the context's CancelFunc, the Close method or the CloseAtDeadline method.

After the process was killed due to context.CancelFunc, Close or CloseAtDeadline, I/O operations return ErrDeadline.

If it stops executing due to a signal from outside this application, I/O operations return an ErrKilledFromOutside.

If it exits on its own, I/O operations return io.EOF if it exited with status 0 (success), and *exec.ExitError in all other exists (non-signal) cases.

func CommandContext

func CommandContext(ctx context.Context, bin string, args []string, env []string) (*Cmd, error)

CommandContext creates a command with a given context, which allows for cancellation / deadlines and for providing a logger via the ContextWithLog function.

The process must be started using the Start() method.

func (*Cmd) Close

func (c *Cmd) Close() (err error)

func (*Cmd) CloseAtDeadline

func (c *Cmd) CloseAtDeadline(deadline time.Time) error

CloseAtDeadline sets a timer to close the process at a specific time in in the future. A zero value for deadline stops the timer.

Note on net.Conn deadlines:

Closing the 'connection' when missing a deadline does not comply with the specified behavior of net.Conn, hence it is incorrect to mimic a net.Conn with *rwcccmd.Cmd

The reason why this is functionality cannot be provided is that *os.File does not provide a way to cancel a Read & Write by other means than calling Close, which may not fit all use cases.

func (*Cmd) Kill

func (c *Cmd) Kill() error

func (*Cmd) Pid

func (c *Cmd) Pid() int

func (*Cmd) Read

func (c *Cmd) Read(out []byte) (n int, err error)

func (*Cmd) Start

func (c *Cmd) Start() error

func (*Cmd) WaitStatus

func (c *Cmd) WaitStatus() (ws syscall.WaitStatus, ok bool)

func (*Cmd) Write

func (c *Cmd) Write(out []byte) (n int, err error)

type Logger

type Logger interface {
	Printf(format string, args ...interface{})
}

The interface a logger must implement for ContextWithLog