ifrit

Documentation

Overview

A process model for go.

Ifrit is a small set of interfaces for composing single-purpose units of work into larger programs. Users divide their program into single purpose units of work, each of which implements the `Runner` interface Each `Runner` can be invoked to create a `Process` which can be monitored and signaled to stop.

The name Ifrit comes from a type of daemon in arabic folklore.

Ifrit ships with a standard library which contains packages for common processes - such as http servers - alongside packages which model process supervision and orchestration - such as process groups and restart strategies. Composing `Runners` together to forms a larger `Runner` which invokes multiple processes.

The advantage of small, single-responsibility processes is that they are simple, and thus can be made reliable. Ifrit's specifications are designed to be free of race conditions and edge cases, allowing larger orcestrated process to also be made reliable. The overall effect is less code and more reliability as your system grows with grace.

Index

• type Process
  • func Background(r Runner) Process
  • func Envoke(r Runner) Process
  • func Invoke(r Runner) Process
• type RunFunc
  • func (r RunFunc) Run(signals <-chan os.Signal, ready chan<- struct{}) error
• type Runner

Types

type Process

type Process interface {
	// Ready returns a channel which will close once the runner is active
	Ready() <-chan struct{}

	// Wait returns a channel that will emit a single error once the Process exits.
	Wait() <-chan error

	// Signal sends a shutdown signal to the Process.  It does not block.
	Signal(os.Signal)
}

A Process represents a Runner that has been started. It is safe to call any method on a Process even after the Process has exited.

func Background

func Background(r Runner) Process

Background executes a Runner and returns a Process immediately, without waiting.

func Envoke

func Envoke(r Runner) Process

Envoke is deprecated in favor of Invoke, on account of it not being a real word.

func Invoke

func Invoke(r Runner) Process

Invoke executes a Runner and returns a Process once the Runner is ready. Waiting for ready allows program initializtion to be scripted in a procedural manner. To orcestrate the startup and monitoring of multiple Processes, please refer to the ifrit/grouper package.

type RunFunc

type RunFunc func(signals <-chan os.Signal, ready chan<- struct{}) error

The RunFunc type is an adapter to allow the use of ordinary functions as Runners. If f is a function that matches the Run method signature, RunFunc(f) is a Runner object that calls f.

func (RunFunc) Run

func (r RunFunc) Run(signals <-chan os.Signal, ready chan<- struct{}) error

type Runner

type Runner interface {
	Run(signals <-chan os.Signal, ready chan<- struct{}) error
}

A Runner defines the contents of a Process. A Runner implementation performs an aribtrary unit of work, while waiting for a shutdown signal. The unit of work should avoid any orchestration. Instead, it should be broken down into simpler units of work in seperate Runners, which are then orcestrated by the ifrit standard library.

An implementation of Runner has the following responibilities:

• setup within a finite amount of time.
• close the ready channel when setup is complete.
• once ready, perform the unit of work, which may be infinite.
• respond to shutdown signals by exiting within a finite amount of time.
• return nil if shutdown is successful.
• return an error if an exception has prevented a clean shutdown.

By default, Runners are not considered restartable; Run will only be called once. See the ifrit/restart package for details on restartable Runners.