pythia

Documentation

Index

• Variables
• func LocalAddr() (net.Addr, error)
• func ParseAddr(description string) (net.Addr, error)
• type Component
• type ComponentInfo
• type Conn
  • func Dial(addr net.Addr) (*Conn, error)
  • func DialRetry(addr net.Addr) *Conn
  • func WrapConn(conn net.Conn) *Conn
  • func (c *Conn) Close() error
  • func (c *Conn) Receive() <-chan Message
  • func (c *Conn) Send(msg Message) error
• type Listener
  • func Listen(addr net.Addr) (*Listener, error)
  • func (l *Listener) Accept() (*Conn, error)
  • func (l *Listener) Close() error
• type Message
  • func (msg Message) String() string
• type MsgType
• type Status
• type Task
  • func (task Task) String() string

Variables

var (
	// The address on which the queue listens.
	QueueAddr, _ = ParseAddr("127.0.0.1:9000")

	// The interval at which to send keep-alive messages on idle connections.
	// This setting shall be set before any Conn has been created, and shall not
	// be altered afterwards.
	KeepAliveInterval = 30 * time.Second

	// Initial interval between dial tries. After each failed attempt, the
	// interval is doubled, up to MaxRetryInterval.
	InitialRetryInterval = 32 * time.Millisecond

	// Maximum time interval between dial tries.
	MaxRetryInterval = 5 * time.Minute
)

Global configuration

var Components = make(map[string]ComponentInfo)

The global Components map contains all registered component types.

Functions

func LocalAddr

func LocalAddr() (net.Addr, error)

LocalAddr returns a random local unix address located in the system's temporary directory.

func ParseAddr

func ParseAddr(description string) (net.Addr, error)

ParseAddr parses an address description into an address. If the description starts with "unix:", the result will be a Unix domain socket address with the path being the rest of the description string. Otherwise, the result will be a TCP address represented by the whole description string.

Types

type Component

type Component interface {
	// Parse the command line arguments given by args and configure the
	// component.
	Setup(fs *flag.FlagSet, args []string) error

	// Execute the component.
	Run()

	// Shut down the component.
	Shutdown()
}

A Component is meant to be run in its own process, and maybe on a separate machine.

type ComponentInfo

type ComponentInfo struct {
	// CLI name of the component (must be unique).
	// This is also the key of the Components map.
	Name string

	// Short one-line description that can be shown in the CLI.
	Description string

	// Function to create a new component of this type.
	New func() Component
}

A ComponentInfo is a type of component. Each type registers in the global Components map.

type Conn

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

Conn is a wrapper over net.Conn, reading and writing Messages.

func Dial

func Dial(addr net.Addr) (*Conn, error)

Dial connects to the address addr and returns a Message-oriented connection.

func DialRetry

func DialRetry(addr net.Addr) *Conn

DialRetry is equivalent to Dial, but it keeps on retrying (with exponential back-off) until the connection is established.

func WrapConn

func WrapConn(conn net.Conn) *Conn

WrapConn wraps a stream network connection into a Message-oriented connection. The raw conn connection shall not be used by the user anymore.

func (*Conn) Close

func (c *Conn) Close() error

Close closes the connection. The receive channel will also be closed. Further sends will cause errors.

func (*Conn) Receive

func (c *Conn) Receive() <-chan Message

Receive returns the channel from which incoming messages can be retrieved. The channel is closed when the connection is closed.

func (*Conn) Send

func (c *Conn) Send(msg Message) error

Send sends a message through the connection.

type Listener

type Listener struct {
	// The address on which the listener listens
	Addr net.Addr
	// contains filtered or unexported fields
}

Listener is a wrapper around net.Listener providing a Message-oriented interface.

func Listen

func Listen(addr net.Addr) (*Listener, error)

Listen announces on address addr and listens for connections.

func (*Listener) Accept

func (l *Listener) Accept() (*Conn, error)

Accept waits for and returns the next connection to the listener.

func (*Listener) Close

func (l *Listener) Close() error

Close closes the listener. Any blocked Accept operations will be unblocked and return errors.

type Message

type Message struct {
	// The message.
	Message MsgType `json:"message"`

	// The capacity of the pool. Only for message register-pool.
	Capacity int `json:"capacity,omitempty"`

	// The task identifier. Only for messages launch, done and abort.
	Id string `json:"id,omitempty"`

	// The task to launch. Only for message launch.
	Task *Task `json:"task,omitempty"`

	// The input to feed to the task. Only for message launch.
	Input string `json:"input,omitempty"`

	// The result status of the execution. Only for message done.
	Status Status `json:"status,omitempty"`

	// The result output of the execution. Only for message done.
	Output string `json:"output,omitempty"`
}

A Message is the basic entity that is sent between components. Messages are serialized to JSON.

func (Message) String

func (msg Message) String() string

type MsgType

type MsgType string

Message type. Components may have internal message types starting with a hyphen.

const (
	// Internal message for keeping a connection alive.
	KeepAliveMsg MsgType = "keep-alive"

	// Register a sandbox pool.
	// Pool->Queue
	RegisterPoolMsg MsgType = "register-pool"

	// Request execution of a task.
	// Frontend->Queue, Queue->Pool
	LaunchMsg MsgType = "launch"

	// Job done.
	// Pool->Queue, Queue->Frontend.
	DoneMsg MsgType = "done"

	// Abort job. The receiving end shall send a done message with status abort
	// (or another status if the job has ended meanwhile).
	// Frontend->Queue, Queue->Pool
	AbortMsg MsgType = "abort"
)

type Status

type Status string

Status of a task execution.

const (
	Success  Status = "success"  // finished, output = stdout
	Timeout  Status = "timeout"  // timed out, output = stdout so far
	Overflow Status = "overflow" // stdout too big, output = capped stdout
	Abort    Status = "abort"    // aborted by abort message, no output
	Crash    Status = "crash"    // sandbox crashed, output = stdout
	Error    Status = "error"    // (maybe temporary) error, output = error message
	Fatal    Status = "fatal"    // unrecoverable error (e.g. misformatted task), output = error message
)

type Task

type Task struct {
	// Environment is the name of the root filesystem.
	Environment string `json:"environment"`

	// TaskFS is the relative path to the task filesystem.
	TaskFS string `json:"taskfs"`

	// Execution limits to be enforced in the sandbox.
	Limits struct {
		// Maximum execution time in seconds.
		Time int `json:"time"`

		// Total amount of main memory (in megabytes) allocated
		// to the sandbox VM.
		Memory int `json:"memory"`

		// Fraction (in percents) of main memory that can be used as disk space
		// in a tmpfs. Note that only used disk space is allocated.
		Disk int `json:"disk"`

		// Maximum size of the output (in bytes).
		Output int `json:"output"`
	} `json:"limits"`
}

Task is the description of a task to be run in a sandbox.

func (Task) String

func (task Task) String() string