README

Ifrit - 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. It's a play on the unix term 'daemon' to indicate a process that is managed by the init system.

Ifrit ships with a standard library which contains packages for common processes - http servers, integration test helpers - alongside packages which model process supervision and orchestration. These packages can be combined to form complex servers which start and shutdown cleanly.

The advantage of small, single-responsibility processes is that they are simple, and thus can be made reliable. Ifrit's interfaces 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.

The full documentation is written in godoc, and can be found at:

http://godoc.org/github.com/tedsuo/ifrit

Expand ▾ Collapse ▴

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. It's a play on the unix term 'daemon' to indicate a process that is managed by the init system.

    Ifrit ships with a standard library which contains packages for common processes - http servers, integration test helpers - alongside packages which model process supervision and orchestration. These packages can be combined to form complex servers which start and shutdown cleanly.

    The advantage of small, single-responsibility processes is that they are simple, and thus can be made reliable. Ifrit's interfaces 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

    Constants

    This section is empty.

    Variables

    This section is empty.

    Functions

    This section is empty.

    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.

                Directories

                Path Synopsis
                fake_runner contains test fixtures.
                fake_runner contains test fixtures.
                Ginkgomon provides ginkgo test helpers.
                Ginkgomon provides ginkgo test helpers.
                Grouper implements process orcestration.
                Grouper implements process orcestration.
                The restart package implements common restart strategies for ifrit processes.
                The restart package implements common restart strategies for ifrit processes.