application

README

What's that?

application is a Go package that implements an application infrastructure.

An application is seen as a set of loops, each running on a separate goroutines. The package provides a way to supervise the lifecycle of these loops.

Usage

For an usage example see here.

Install

go install https://github.com/remogatto/application

License

See LICENSE.

Documentation

Overview

Package application implements a simple infrastructure for building concurrent programs.. An application is considered as a set of loops which interact each other. The application package is responsibile for the lifecycle of these loops.

Index

• Variables
• func Debugf(fmt string, v ...interface{})
• func Exit()
• func InstallSignalHandler(handler SignalHandler)
• func Logf(fmt string, v ...interface{})
• func Printf(fmt string, v ...interface{})
• func Register(name string, loop Looper) error
• func Run()
• func Start(name string) (err error)
• func UninstallSignalHandler(handler SignalHandler)
• type BaseLoop
  • func NewBaseLoop() *BaseLoop
  • func (baseLoop *BaseLoop) Pause() chan int
  • func (baseLoop BaseLoop) Run()
  • func (baseLoop *BaseLoop) Terminate() chan int
• type Error
  • func (e Error) Error() string
• type Looper
  • func Loop(name string) (Looper, error)
• type RerunError
  • func (e RerunError) Error() string
• type SignalHandler

Variables

var (
	// NumLoops is the number of registered loops.
	NumLoops int

	// Verbose is a boolean flag. If true it enables a lot of
	// console output.
	Verbose bool

	// Verbose is a boolean flag. If true it enables a lot of
	// debugging output.
	Debug bool

	// ErrorCh is a receive-only channel from which client code
	// receive errors from application.
	ErrorCh <-chan interface{}

	// Exit receive a boolean value when the application exits.
	ExitCh <-chan bool
)

Functions

func Debugf

func Debugf(fmt string, v ...interface{})

Debugf is an helper function that produces formatted log. Debugf produces output only if Debug variable is true.

func Exit

func Exit()

SendExit initiates the termination process.

func InstallSignalHandler

func InstallSignalHandler(handler SignalHandler)

Installs the specified handler. Trying to re-install an already installed handler is effectively a NOOP.

func Logf

func Logf(fmt string, v ...interface{})

Logf is an helper function that produces formatted log. Logf produces output only if Verbose variable is true.

func Printf

func Printf(fmt string, v ...interface{})

Printf is an helper function that produces formatted log.

func Register

func Register(name string, loop Looper) error

Register registers a loop.

func Run

func Run()

Run starts the all the registered loops in separated goroutines. It blocks until Exit() is called. When the application is terminated, it terminates all the registered loops. This is a procedure of two phases:

1. Pause all event loops (i.e: stop all tickers)
2. Terminate all event loops

The two phases are required because we have no idea what the relationship among the event-loops might be. We are assuming the worst case scenario in which the relationships among event-loops form a graph - in such a case it is unclear whether an event-loop can be terminated without knowing that all event-loops are paused.

func Start

func Start(name string) (err error)

Start (re)starts the named loop in a separated goroutine. If the goroutine panics, the error is recovered and sent to the error channel.

func UninstallSignalHandler

func UninstallSignalHandler(handler SignalHandler)

Uninstalls the specified handler. Trying to uninstall an non-existent handler is effectively a NOOP.

Types

type BaseLoop

type BaseLoop struct {
	PauseCh, TerminateCh chan int
}

func NewBaseLoop

func NewBaseLoop() *BaseLoop

func (*BaseLoop) Pause

func (baseLoop *BaseLoop) Pause() chan int

func (BaseLoop) Run

func (baseLoop BaseLoop) Run()

func (*BaseLoop) Terminate

func (baseLoop *BaseLoop) Terminate() chan int

type Error

type Error struct {
	RuntimeError interface{}
	Stack        string
}

func (Error) Error

func (e Error) Error() string

type Looper

type Looper interface {
	// Run runs the loop.
	// Usually Run contains a for {} statement.
	Run()

	// Pause returns a chan int channel.
	// Values sent to this channel will pause the loop.
	Pause() chan int

	// Terminate returns a chan int channel.
	// Values sent to this channel will terminate the loop.
	Terminate() chan int
}

Looper is an interface for application's loops.

func Loop

func Loop(name string) (Looper, error)

Loop returns a registered loop.

type RerunError

type RerunError struct {
	ApplicationError Error
}

func (RerunError) Error

func (e RerunError) Error() string

type SignalHandler

type SignalHandler interface {
	// Function to be called upon receiving an os.Signal.
	//
	// A single signal is passed to all installed signal handlers.
	// The [order in which this function is called in respect to other handlers] is unspecified.
	HandleSignal(signal os.Signal)
}