c

Documentation

Index

• Variables
• func GetNodeName(ctx context.Context) (string, bool)
• func WithoutCancel(ctx context.Context) context.Context
• type Child
  • func (c Child) GetName() string
  • func (c Child) GetRuntimeName() string
  • func (c Child) GetSpec() ChildSpec
  • func (c Child) GetTag() ChildTag
  • func (c Child) IsWorker() bool
  • func (ch Child) Terminate() (bool, error)
• type ChildNotification
  • func (ce ChildNotification) GetName() string
  • func (ce ChildNotification) RuntimeName() string
  • func (ce ChildNotification) Unwrap() error
• type ChildSpec
  • func New(name string, startFn func(context.Context) error, opts ...Opt) ChildSpec
  • func NewWithNotifyStart(name string, startFn func(context.Context, NotifyStartFn) error, opts ...Opt) ChildSpec
  • func (chSpec ChildSpec) DoStart(startCtx context.Context, supName string, ...) (Child, error)
  • func (chSpec ChildSpec) DoesCapturePanic() bool
  • func (chSpec ChildSpec) GetName() string
  • func (chSpec ChildSpec) GetRestart() Restart
  • func (chSpec ChildSpec) GetTag() ChildTag
  • func (chSpec ChildSpec) IsWorker() bool
• type ChildTag
  • func (ct ChildTag) String() string
• type NotifyStartFn
• type Opt
  • func WithCapturePanic(capture bool) Opt
  • func WithRestart(r Restart) Opt
  • func WithShutdown(s Shutdown) Opt
  • func WithTag(t ChildTag) Opt
  • func WithTolerance(maxErrCount uint32, errWindow time.Duration) Opt
• type Restart
  • func (r Restart) String() string
• type Shutdown
  • func Timeout(d time.Duration) Shutdown
• type ShutdownTag

Variables

var Indefinitely = Shutdown{/* contains filtered or unexported fields */}

Indefinitely specifies the parent supervisor must wait indefinitely for child goroutine to stop executing

Functions

func GetNodeName

func GetNodeName(ctx context.Context) (string, bool)

GetNodeName gets a capataz worker name from a context

func WithoutCancel

func WithoutCancel(ctx context.Context) context.Context

WithoutCancel returns a context that is never canceled.

Types

type Child

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

Child is the runtime representation of a Spec

func (Child) GetName

func (c Child) GetName() string

GetName returns the name of the `ChildSpec` of this child

func (Child) GetRuntimeName

func (c Child) GetRuntimeName() string

GetRuntimeName returns the name of this child (once started). It will have a prefix with the supervisor name

func (Child) GetSpec

func (c Child) GetSpec() ChildSpec

GetSpec returns the `ChildSpec` of this child

func (Child) GetTag

func (c Child) GetTag() ChildTag

GetTag returns the ChildTag of this ChildSpec

func (Child) IsWorker

func (c Child) IsWorker() bool

IsWorker indicates if this child is a worker

func (Child) Terminate

func (ch Child) Terminate() (bool, error)

Terminate is a synchronous procedure that halts the execution of the child. The first return value is false if the worker is already terminated. The second return value is non-nil when the child fails to terminate. If the first return value is true, the second return value will always be nil.

type ChildNotification

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

ChildNotification reports when a child has terminated; if it terminated with an error, it is set in the err field, otherwise, err will be nil.

func (ChildNotification) GetName

func (ce ChildNotification) GetName() string

GetName returns the spec name of the child that emitted this notification

func (ChildNotification) RuntimeName

func (ce ChildNotification) RuntimeName() string

RuntimeName returns the runtime name of the child that emitted this notification

func (ChildNotification) Unwrap

func (ce ChildNotification) Unwrap() error

Unwrap returns the error reported by ChildNotification, if any.

type ChildSpec

type ChildSpec struct {
	Name         string
	Tag          ChildTag
	Shutdown     Shutdown
	Restart      Restart
	CapturePanic bool

	Start func(context.Context, NotifyStartFn) error
}

ChildSpec represents a Child specification; it serves as a template for the construction of a goroutine. The ChildSpec record is used in conjunction with the supervisor's SupervisorSpec.

A note about ChildTag

An approach that we considered was to define a type heriarchy for SupervisorChildSpec and WorkerChildSpec to deal with differences between Workers and Supervisors rather than having a value you can use in a switch statement. In reality, the differences between the two are minimal (only behavior change happens when sending notifications to the events system). If this changes, we may consider a design where we have a ChildSpec interface and we have different implementations.

func New

func New(name string, startFn func(context.Context) error, opts ...Opt) ChildSpec

New creates a `ChildSpec` that represents a worker goroutine. It requires two arguments: a `name` that is used for runtime tracing and a `startFn` function.

### The `name` argument

The `name` argument must not be empty nor contain forward slash characters (e.g. `/`), otherwise, the system will panic. This method is preferred as opposed to return an error given it is considered a bad implementation (ideally a compilation error).

### The `startFn` argument

The `startFn` function where your business logic should be located. This attribute of a `ChildSpec` is going to be used to spawn a new supervised goroutine.

The `startFn` function will receive a `context.Context` record that _must_ be used inside your business logic to accept stop signals from it's parent supervisor.

Depending on the `Shutdown` values used in the `ChildSpec` , if the `startFn` function does not respect the given context, the parent supervisor will either block forever or leak goroutines after a timeout has been reached.

func NewWithNotifyStart

func NewWithNotifyStart(
	name string,
	startFn func(context.Context, NotifyStartFn) error,
	opts ...Opt,
) ChildSpec

NewWithNotifyStart accomplishes the same goal as `New` with the addition of passing a `notifyStart` callback function to the `start` parameter.

### The `NotifyStartFn` argument

The `NotifyStartFn` is a callback that allows the spawned worker goroutine to signal when it has officially started. Is essential to call this callback function in your business logic as soon as you consider the worker is initialized, otherwise the parent supervisor will block and eventually fail with a timeout.

#### Report a start error on `NotifyStartFn`

If for some reason, a child is not able to start correctly, the child should call the `NotifyStartFn` function with the start `error`.

func (ChildSpec) DoStart

func (chSpec ChildSpec) DoStart(
	startCtx context.Context,
	supName string,
	supNotifyChan chan<- ChildNotification,
) (Child, error)

DoStart spawns a new goroutine that will execute the `Start` attribute of the ChildSpec, this function will block until the spawned goroutine notifies it has been initialized.

### The supNotifyChan value

Messages sent to this channel notify the supervisor that the child's goroutine has finished (either with or without an error). The runtime name of the child is also given so that the supervisor can use the spec for that child when restarting.

func (ChildSpec) DoesCapturePanic

func (chSpec ChildSpec) DoesCapturePanic() bool

DoesCapturePanic indicates if this child handles panics

func (ChildSpec) GetName

func (chSpec ChildSpec) GetName() string

GetName returns the specified name for a Child Spec

func (ChildSpec) GetRestart

func (chSpec ChildSpec) GetRestart() Restart

GetRestart returns the Restart setting for this ChildSpec

func (ChildSpec) GetTag

func (chSpec ChildSpec) GetTag() ChildTag

GetTag returns the ChildTag of this ChildSpec

func (ChildSpec) IsWorker

func (chSpec ChildSpec) IsWorker() bool

IsWorker indicates if this child is a worker

type ChildTag

type ChildTag uint32

ChildTag specifies the type of Child that is running, this is a closed set given we only will support workers and supervisors

const (
	// Worker is used for a c.Child that run a business-logic goroutine
	Worker ChildTag = iota
	// Supervisor is used for a c.Child that runs another supervision tree
	Supervisor
)

func (ChildTag) String

func (ct ChildTag) String() string

type NotifyStartFn

type NotifyStartFn = func(startError)

NotifyStartFn is a function given to supervisor children to notify the supervisor that the child has started.

### Notify child's start failure

In case the child cannot get started it should call this function with an error value different than nil.

type Opt

type Opt func(*ChildSpec)

Opt is used to configure a child's specification

func WithCapturePanic

func WithCapturePanic(capture bool) Opt

WithCapturePanic specifies if panics raised by this worker should be treated as errors. restartable errors.

func WithRestart

func WithRestart(r Restart) Opt

WithRestart specifies how the parent supervisor should restart this worker after an error is encountered.

func WithShutdown

func WithShutdown(s Shutdown) Opt

WithShutdown specifies how the shutdown of the worker is going to be handled. Read `Indefinitely` and `Timeout` shutdown values documentation for details.

func WithTag

func WithTag(t ChildTag) Opt

WithTag sets the given c.ChildTag on a c.ChildSpec

func WithTolerance

func WithTolerance(maxErrCount uint32, errWindow time.Duration) Opt

WithTolerance specifies to the supervisor monitor of this worker how many errors it should be willing to tolerate before giving up restarting it and fail.

type Restart

type Restart uint32

Restart specifies when a goroutine gets restarted

const (
	// Permanent specifies that the goroutine should be restarted any time there
	// is an error. If the goroutine is finished without errors, it is restarted
	// again.
	Permanent Restart = iota

	// Transient specifies that the goroutine should be restarted if and only if
	// the goroutine failed with an error. If the goroutine finishes without
	// errors it is not restarted again.
	Transient

	// Temporary specifies that the goroutine should not be restarted, not even
	// when the goroutine fails
	Temporary
)

func (Restart) String

func (r Restart) String() string

type Shutdown

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

Shutdown indicates how the parent supervisor will handle the stoppping of the child goroutine.

func Timeout

func Timeout(d time.Duration) Shutdown

Timeout specifies a duration of time the parent supervisor will wait for the child goroutine to stop executing

### WARNING:

A point worth bringing up is that golang *does not* provide a hard kill mechanism for goroutines. There is no known way to kill a goroutine via a signal other than using `context.Done` and the goroutine respecting this mechanism. If the timeout is reached and the goroutine does not stop, the supervisor will continue with the shutdown procedure, possibly leaving the goroutine running in memory (e.g. memory leak).

type ShutdownTag

type ShutdownTag uint32

ShutdownTag specifies the type of Shutdown strategy that is used when stopping a goroutine