Pkg.go.dev is a new destination for Go discovery & docs. Check it out at pkg.go.dev/cirello.io/supervisor and share your feedback.

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

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

❖ const AlwaysRestart = -1

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

Permanent services are always restarted

Temporary services are never restarted.

Transient services are restarted only when panic.

❖ 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).

Example 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()

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 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 func(*ServiceSpecification)

ServiceOption modifies the service specifications.

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

ServiceSpecification defines how a service is executed by the supervisor.

❖ 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.

Example 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 (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 (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.

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

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

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.

Services return a list of services