channeler

README

channeler

A Go package that wires up a command-line shell with channels.

Documentation

Overview

Package channeler wires up a command-line shell with channels.

Index

• Constants
• Variables
• type ChParams
  • func (p *ChParams) Validate() error
• type Channels
  • func Start(p *ChParams) (*Channels, error)

Constants

const NewLineCh = '\n'

Variables

var VerboseLoggingEnabled = false

VerboseLoggingEnabled can be set true to see detailed logging.

Types

type ChParams

type ChParams struct {
	// Path is either the absolute path to the executable, or a $PATH
	// relative command name.
	Path string

	// Args has the arguments, flags and flag arguments for the
	// shell invocation.
	Args []string

	// WorkingDir is the working directory of the shell process.
	WorkingDir string

	// CommandTerminator, if not 0, is appended to the end of every command.
	// This is a convenience for shells like mysql that want such things.
	// Example: ';'
	CommandTerminator byte

	// BuffSizeIn is how many commands can be added before
	// StdIn will block.
	BuffSizeIn int

	// ChTimeoutIn is how long to wait for a command from stdIn
	// before we fail, suspecting a deadlock or some other irreconcilable
	// problem in the client.  If you have a command sequence A, B, and you
	// know command A will take 2 hours to run, then this value should
	// exceed 2 hours, to avoid a timeout waiting to receive command B.
	// An expired timeout results in an error on the Done channel.
	// This can be long, and maybe it should be removed completely
	// (effectively treated as infinite).
	// Increasing BuffSizeIn doesn't help here.
	ChTimeoutIn time.Duration

	// BuffSizeOut is how many lines of output can be accepted
	// from the shell's stdout before back pressure is applied,
	// forcing the shell to wait before its output is consumed.
	BuffSizeOut int

	// BuffSizeErr is like BuffSizeOut, except for stderr.
	BuffSizeErr int

	// ChTimeout is how long back pressure from stdOut and stdErr
	// consumption is allowed to stall things before we fail,
	// suspecting a deadlock in consumer code.
	// An expired timeout results in an error on the Done channel.
	// To avoid timeouts, increase buffer BuffSizeOut and/or BuffSizeErr
	// and/or consume output faster.
	ChTimeoutOut time.Duration
}

ChParams captures all parameters to channeler.Start. It's a mix of subprocess parameters, like Path and Args, and orchestration parameters like buffer sizes and timeouts.

func (*ChParams) Validate

func (p *ChParams) Validate() error

type Channels

type Channels struct {
	// StdIn accepts command lines. A "command line" is opaque;
	// it might be complex, multi-line script, like a bash here-doc.
	// It's sent to the shell without any processing other than the
	// addition of a terminating NewLine if one isn't present.
	// Close StdIn to initiate graceful shutdown of the shell.
	StdIn chan<- string
	// Block on this after closing StdIn to assure that
	// everything finishes without an error.  An error here
	// is usually a timeout.  An error here has nothing to do
	// with the content of StdErr; the latter is merely another
	// output stream from the subprocess.
	Done <-chan error
	// StdOut provides lines from stdout with NewLine removed.
	StdOut <-chan string
	// StdErr provides lines from stderr with NewLine removed.
	StdErr <-chan string
}

Channels holds a shell's input and output channels.

func Start

func Start(p *ChParams) (*Channels, error)

Start starts a shell subprocess, and returns all the channels needed to interact with and control it. To stop the shell, close it's input channel.