port

Documentation

Overview

Package port provides a [Runnable] used to interact with external system processes (ExtProg). It uses the os.Exec.Cmd subsystem from the stdlib, but wraps it with Processes. This provides the following guarantees:

1. A Port must be started by another process. This process will be known as the PortOwner.

2. When the ExtProg exits, the PortOwner will receive an erl.ExitMsg if it is non-zero. If the process exits cleanly, it will have exitreason.Normal and will be ignored by the PortOwner unless it is trapping exits (this is behavior that applies to all processes). However an ExtProg returning non-zero exit code will cause the PortOwner to crash (if not trapping exits).

3. If the ReturnExitStatus option is set, the PortOwner will receive a [PortExited] msg, regardless of the ExtProg exit code.

4. By default, the stdout of the ExtProg will sent to the PortOwner, line by line, as a [PortMessage]. Alternative decoding options can be set when opening the port by provding a bufio.SplitFunc or using one of the existing Decode* Opts in this package. To send this output else where, use SetStdOut with a *os.File or buffer, or IgnoreStdOut to ignore output completely.

5. Data can be sent to the ExtProg via stdin via [PortCommand] messages. It is up to the sender to format the messages in a way the ExtProg can parse.

The above features allow for asynchronous management of both long-running and transient ExtProgs, integrated into a supervision tree.

Index

• Variables
• func Cast(port erl.PID, msg []byte)
• func Close(self erl.PID, port erl.PID)
• func DecodeNumBytesSplitFun(num int) bufio.SplitFunc
• func Open(self erl.PID, cmd Cmd, opts ...Opt) erl.PID
• type Closed
• type Cmd
  • func NewCmd(cmd string, args ...string) Cmd
• type Command
• type ErrMessage
• type Exited
• type Message
• type Opt
  • func CustomDecoder(splitFun bufio.SplitFunc) Opt
  • func DecodeLines() Opt
  • func DecodeNULs() Opt
  • func DecodeNumBytes(num int) Opt
  • func IgnoreStdOut() Opt
  • func ReceiveStdErr(splitFunc bufio.SplitFunc) Opt
  • func ReturnExitStatus() Opt
  • func SetExitSignal(sig syscall.Signal) Opt
  • func SetStdErr(stderr io.Writer) Opt
  • func SetStdOut(stdout io.Writer) Opt
• type Opts
• type Port
  • func (p *Port) Receive(self erl.PID, inbox <-chan any) error

Variables

var DecodeLinesSplitFun = bufio.ScanLines

var DecodeNULSplitFun = func(data []byte, atEOF bool) (advance int, token []byte, err error) {
	if atEOF && len(data) == 0 {
		return 0, nil, nil
	}
	if i := bytes.IndexByte(data, '\000'); i >= 0 {

		return i + 1, data[0:i], nil
	}

	if atEOF {
		return len(data), data, nil
	}

	return 0, nil, nil
}

Functions

func Cast

func Cast(port erl.PID, msg []byte)

sends an asynchronous command to the port which will be sent to the external procs stdin. It's the callers responsibility to encode [msg] to a format the external program understands.

func Close

func Close(self erl.PID, port erl.PID)

Closes a port. A [PortExited] message will be sent to the sender and the PortOwner

func DecodeNumBytesSplitFun

func DecodeNumBytesSplitFun(num int) bufio.SplitFunc

func Open

func Open(self erl.PID, cmd Cmd, opts ...Opt) erl.PID

Opens a port.

TODO: list all options here.

Types

type Closed

type Closed struct {
	Port erl.PID
	// the exit error of the ExtProg, if any
	Err error
}

type Cmd

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

func NewCmd

func NewCmd(cmd string, args ...string) Cmd

the external program to run [cmd] and a list of its arguments

type Command

type Command []byte

type ErrMessage

type ErrMessage struct {
	Port erl.PID
	Data []byte
}

Received from a port error stream

type Exited

type Exited struct {
	Port erl.PID
	Err  error
}

returned when the port process returns and ReturnExitStatus is true. if [err] is not nil, it may be an *os/exec.ExitError

type Message

type Message struct {
	Port erl.PID
	Data []byte
}

decocded data from the ExtProg stdout

type Opt

type Opt func(opts Opts) Opts

func CustomDecoder

func CustomDecoder(splitFun bufio.SplitFunc) Opt

func DecodeLines

func DecodeLines() Opt

Port messages will be parsed by \n

func DecodeNULs

func DecodeNULs() Opt

Port messages will be parsed as NUL delimited strings

func DecodeNumBytes

func DecodeNumBytes(num int) Opt

Will read [num] bytes from the external command before returning a message to the port owner.

func IgnoreStdOut

func IgnoreStdOut() Opt

Causing stdout to be redirected to a null device. The PortOwner should recieve no [PortMessage]s while this is set.

func ReceiveStdErr

func ReceiveStdErr(splitFunc bufio.SplitFunc) Opt

If set, the PortOwner will receive the data from the ExtProg error stream as [PortErrMessage]s. Not all programs will return error messages in the saem format as stdout, this option accepts a distinct bufio.Splitfunc to use for stderr.

func ReturnExitStatus

func ReturnExitStatus() Opt

This will cause the exit status to be returend to the PortOwner

func SetExitSignal

func SetExitSignal(sig syscall.Signal) Opt

If set, this signal will be sent to the ExtProg during port shutdown in addition to closing stdin

func SetStdErr

func SetStdErr(stderr io.Writer) Opt

Redirect ExtProg stderr stream to this item. Works the same way as SetStdOut

func SetStdOut

func SetStdOut(stdout io.Writer) Opt

Redirect stdout to an *os.File or buffer. A buffer or file should be safe for other processes to read after the erl.ExitMsg is received for the port

type Opts

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

type Port

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

func (*Port) Receive

func (p *Port) Receive(self erl.PID, inbox <-chan any) error