cirello.io: cirello.io/supervisor Index | Examples | Files | Directories

package supervisor

import "cirello.io/supervisor"

Package supervisor provides supervisor trees for Go applications.

DEPRECATED: consider using cirello.io/oversight

This package implements supervisor trees, similar to what Erlang runtime offers. It is built on top of context package, with all of its advantages, namely the possibility trickle down context-related values and cancelation signals.

A supervisor tree can be composed either of services or other supervisors - each supervisor can have its own set of configurations. Any instance of supervisor.Service can be added to a tree.

Supervisor
     ├─▶ Supervisor (if one service dies, only one is restarted)
     │       ├─▶ Service
     │       └─▶ Service
     ├─▶ Group (if one service dies, all others are restarted too)
     │       └─▶ Service
     │           Service
     │           Service
     └─▶ Service

Example:

package main

import (
	"fmt"
	"os"
	"os/signal"
	"time"

	"cirello.io/supervisor"
	"context"
)

type Simpleservice int

func (s *Simpleservice) String() string {
	return fmt.Sprintf("simple service %d", int(*s))
}

func (s *Simpleservice) Serve(ctx context.Context) {
	for {
		select {
		case <-ctx.Done():
			return
		default:
			fmt.Println("do something...")
			time.Sleep(500 * time.Millisecond)
		}
	}
}

func main(){
	var supervisor supervisor.Supervisor

	svc := Simpleservice(1)
	supervisor.Add(&svc)

	// Simply, if not special context is needed:
	// supervisor.Serve()
	// Or, using context.Context to propagate behavior:
	c := make(chan os.Signal, 1)
	signal.Notify(c, os.Interrupt)
	ctx, cancel := context.WithCancel(context.Background())
	go func(){
		<-c
		fmt.Println("halting supervisor...")
		cancel()
	}()

	supervisor.Serve(ctx)
}

TheJerf's blog post about Suture is a very good and helpful read to understand how this package has been implemented.

This is package is inspired by github.com/thejerf/suture

http://www.jerf.org/iri/post/2930

Index

Examples

Package Files

anon.go doc.go group.go helpers.go supervisor.go

Constants

const AlwaysRestart = -1

AlwaysRestart adjusts the supervisor to never halt in face of failures.

func Permanent Uses

func Permanent(s *ServiceSpecification)

Permanent services are always restarted

func Temporary Uses

func Temporary(s *ServiceSpecification)

Temporary services are never restarted.

func Transient Uses

func Transient(s *ServiceSpecification)

Transient services are restarted only when panic.

type Group Uses

type Group struct {
    *Supervisor
}

Group is a superset of Supervisor datastructure responsible for offering a supervisor tree whose all services are restarted whenever one of them fail or is restarted. It assumes that all services rely on each other. It implements Service, therefore it can be nested if necessary either with other Group or Supervisor. When passing the Group around, remind to do it as reference (&group).

Code:

supervisor := supervisor.Group{
    Supervisor: &supervisor.Supervisor{},
}

svc1 := &Simpleservice{id: 1}
svc1.Add(1)
supervisor.Add(svc1)
svc2 := &Simpleservice{id: 2}
svc2.Add(1)
supervisor.Add(svc2)

ctx, cancel := context.WithTimeout(context.Background(), 1*time.Second)
go supervisor.Serve(ctx)

svc1.Wait()
svc2.Wait()
cancel()

func (*Group) Serve Uses

func (g *Group) Serve(ctx context.Context)

Serve starts the Group tree. It can be started only once at a time. If stopped (canceled), it can be restarted. In case of concurrent calls, it will hang until the current call is completed.

type Service Uses

type Service interface {
    // Serve is called by a Supervisor to start the service. It expects the
    // service to honor the passed context and its lifetime. Observe
    // <-ctx.Done() and ctx.Err(). If the service is stopped by anything
    // but the Supervisor, it will get started again. Be careful with shared
    // state among restarts.
    Serve(ctx context.Context)
}

Service is the public interface expected by a Supervisor.

This will be internally named after the result of fmt.Stringer, if available. Otherwise it is going to use an internal representation for the service name.

type ServiceOption Uses

type ServiceOption func(*ServiceSpecification)

ServiceOption modifies the service specifications.

type ServiceSpecification Uses

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

ServiceSpecification defines how a service is executed by the supervisor.

type Supervisor Uses

type Supervisor struct {
    // Name for this supervisor tree, used for logging.
    Name string

    // MaxRestarts is the number of maximum restarts given MaxTime. If more
    // than MaxRestarts occur in the last MaxTime, then the supervisor
    // stops all services and halts. Set this to AlwaysRestart to prevent
    // supervisor halt.
    MaxRestarts int

    // MaxTime is the time period on which the internal restart count will
    // be reset.
    MaxTime time.Duration

    // Log is a replaceable function used for overall logging.
    // Default: log.Printf.
    Log func(interface{})
    // contains filtered or unexported fields
}

Supervisor is the basic datastructure responsible for offering a supervisor tree. It implements Service, therefore it can be nested if necessary. When passing the Supervisor around, remind to do it as reference (&supervisor). Once the supervisor is started, its attributes are frozen.

Code:

var supervisor supervisor.Supervisor

svc := &Simpleservice{id: 1}
svc.Add(1)
supervisor.Add(svc)

ctx, cancel := context.WithTimeout(context.Background(), 1*time.Second)
go supervisor.Serve(ctx)

svc.Wait()
cancel()

func (*Supervisor) Add Uses

func (s *Supervisor) Add(service Service, opts ...ServiceOption)

Add inserts into the Supervisor tree a new permanent service. If the Supervisor is already started, it will start it automatically.

func (*Supervisor) AddFunc Uses

func (s *Supervisor) AddFunc(f func(context.Context), opts ...ServiceOption) string

AddFunc inserts into the Supervisor tree a new permanent anonymous service. If the Supervisor is already started, it will start it automatically.

func (*Supervisor) Cancelations Uses

func (s *Supervisor) Cancelations() map[string]context.CancelFunc

Cancelations return a list of services names and their cancelation calls. These calls be used to force a service restart.

func (*Supervisor) Remove Uses

func (s *Supervisor) Remove(name string)

Remove stops the service in the Supervisor tree and remove from it.

func (*Supervisor) Serve Uses

func (s *Supervisor) Serve(ctx context.Context)

Serve starts the Supervisor tree. It can be started only once at a time. If stopped (canceled), it can be restarted. In case of concurrent calls, it will hang until the current call is completed.

func (*Supervisor) Services Uses

func (s *Supervisor) Services() map[string]Service

Services return a list of services

func (*Supervisor) String Uses

func (s *Supervisor) String() string

Directories

PathSynopsis
easyPackage easy is an easier interface to use cirello.io/supervisor.

Package supervisor imports 5 packages (graph) and is imported by 2 packages. Updated 2019-01-03. Refresh now. Tools for package owners.