s

func WithNodes ¶

func WithNodes(nodes ...Node) BuildNodesFn

WithNodes allows the registration of child nodes in a SupervisorSpec. Node records passed to this function are going to be supervised by the Supervisor created from a SupervisorSpec.

Check the documentation of NewSupervisorSpec for more details and examples.

func NewDynSupervisor ¶

func NewDynSupervisor(ctx context.Context, name string, opts ...Opt) (DynSupervisor, error)

NewDynSupervisor creates a DynamicSupervisor which can start workers at runtime in a procedural manner. It receives a context and the supervisor name (for tracing purposes).

When to use a DynSupervisor?

If you want to run supervised worker routines on dynamic inputs. This is something that a regular Supervisor cannot do, as it needs to know the children nodes at construction time.

Differences to Supervisor ¶

As opposed to a Supervisor, a DynSupervisor:

* Cannot receive node specifications to start them in an static fashion

* It is able to spawn workers dynamically

• In case of a hard crash and following restart, it will start with an empty list of children

func NewHealthcheckMonitor ¶

func NewHealthcheckMonitor(
	maxAllowedFailures uint32,
	maxAllowedRestartDuration time.Duration,
) *HealthcheckMonitor

NewHealthcheckMonitor offers a way to monitor a supervision tree health from events emitted by it.

maxAllowedFailures: the threshold beyond which the environment is considered

unhealthy.

maxAllowedRestartDuration: the restart threshold, which if exceeded, indicates

an unhealthy environment. Any process that fails
to restart under the threshold results in an
unhealthy report

func NewDynSubtree ¶

func NewDynSubtree(
	name string,
	startFn func(context.Context, Spawner) error,
	spawnerOpts []Opt,
	opts ...c.Opt,
) Node

NewDynSubtree builds a worker that has receives a Spawner that allows it to create more child workers dynamically in a sub-tree. NewDynSubtree builds a worker that receives a Spawner which allows it to create more child workers dynamically in a sibling sub-tree.

The runtime subtree is composed of a worker and a supervisor ¶

<name> | `- spawner (creates dynamic workers in sibling subtree) | `- subtree

|
`- <dynamic_worker>

Note: The Spawner is automatically managed by the supervision tree, so clients are not required to terminate it explicitly.

func NewDynSubtreeWithNotifyStart ¶

func NewDynSubtreeWithNotifyStart(
	name string,
	runFn func(context.Context, NotifyStartFn, Spawner) error,
	spawnerOpts []Opt,
	opts ...c.Opt,
) Node

NewDynSubtreeWithNotifyStart accomplishes the same goal as NewDynSubtree with the addition of passing an extra argument (notifyStart callback) to the startFn function parameter.

func NewWorker ¶

func NewWorker(name string, startFn func(context.Context) error, opts ...c.Opt) Node

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

The name argument ¶

A 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 is where your business logic should be located. This function will be running on 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 its parent supervisor.

Depending on the Shutdown values used with the WithShutdown settings of the worker, 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 NewWorkerWithNotifyStart ¶

func NewWorkerWithNotifyStart(
	name string,
	startFn func(context.Context, NotifyStartFn) error,
	opts ...c.Opt,
) Node

NewWorkerWithNotifyStart accomplishes the same goal as NewWorker with the addition of passing an extra argument (notifyStart callback) to the startFn function parameter.

The NotifyStartFn argument ¶

Sometimes you want to consider a goroutine started after certain initialization was done; like doing a read from a Database or API, or some socket is bound, etc. The NotifyStartFn is a callback that allows the spawned worker goroutine to signal when it has officially started.

It 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 node is not able to start correctly (e.g. DB connection fails, network is kaput), the node may call the given NotifyStartFn function with the impending error as a parameter. This will cause the whole supervision system start procedure to abort.

func Subtree ¶

func Subtree(subtreeSpec SupervisorSpec, opts ...c.Opt) Node

Subtree transforms SupervisorSpec into a Node. This function allows you to insert a black-box sub-system into a bigger supervised system.

Note the subtree SupervisorSpec is going to inherit the event notifier from its parent supervisor.

Example:

// Initialized a SupervisorSpec that doesn't know anything about other
// parts of the systems (e.g. is self-contained)
networkingSubsystem := cap.NewSupervisorSpec("net", ...)

// Another self-contained system
filesystemSubsystem := cap.NewSupervisorSpec("fs", ...)

// SupervisorSpec that is started in your main.go
cap.NewSupervisorSpec("root",
 cap.WithNodes(
   cap.Subtree(networkingSubsystem),
   cap.Subtree(filesystemSubsystem),
 ),
)

func WithNotifier ¶

func WithNotifier(en EventNotifier) Opt

WithNotifier is an Opt that specifies a callback that gets called whenever the supervision system reports an Event

This function may be used to observe the behavior of all the supervisors in the systems, and it is a great place to hook in monitoring services like logging, error tracing and metrics gatherers

func WithRestartTolerance ¶

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

WithRestartTolerance is a Opt that specifies how many errors the supervisor should be willing to tolerate before giving up restarting and fail.

If the tolerance is met, the supervisor is going to fail, if this is a sub-tree, this error is going to be handled by a grand-parent supervisor, restarting the tolerance again.

Example

// Tolerate 10 errors every 5 seconds
//
// - if there is 11 errors in a 5 second window, it makes the supervisor fail
//
WithRestartTolerance(10, 5 * time.Second)

func WithStartOrder ¶

func WithStartOrder(o Order) Opt

WithStartOrder is an Opt that specifies the start/stop order of a supervisor's children nodes

Possible values may be:

* LeftToRight -- Start children nodes from left to right, stop them from right to left

* RightToLeft -- Start children nodes from right to left, stop them from left to right

func WithStrategy ¶

func WithStrategy(s Strategy) Opt

WithStrategy is an Opt that specifies how children nodes of a supervisor get restarted when one of the nodes fails

Possible values may be:

* OneForOne -- Only restart the failing child

* OneForAll (Not Implemented Yet) -- Restart the failing child and all its siblings[*]

[*] This option may come handy when all the other siblings depend on one another to work correctly.

func NewRestartToleranceReached ¶

func NewRestartToleranceReached(
	tolerance restartTolerance,
	sourceCh c.Child,
	sourceErr error,
	lastErr error,
) *RestartToleranceReached

NewRestartToleranceReached creates an ErrorToleranceReached record

func NewSupervisorSpec ¶

func NewSupervisorSpec(name string, buildNodes BuildNodesFn, opts ...Opt) SupervisorSpec

NewSupervisorSpec creates a SupervisorSpec. It requires the name of the supervisor (for tracing purposes) and some children nodes to supervise.

Monitoring children that do not share resources ¶

This is intended for situations where you need worker goroutines that are self-contained running in the background.

To specify a group of children nodes, you need to use the WithNodes utility function. This function may receive Subtree or Worker nodes.

Example:

cap.NewSupervisorSpec("root",

  // (1)
  // Specify child nodes to spawn when this supervisor starts
  cap.WithNodes(
    cap.Subtree(subtreeSupervisorSpec),
    workerChildSpec,
  ),

  // (2)
  // Specify child nodes start from right to left (reversed order) and
  // stop from left to right.
  cap.WithStartOrder(cap.RightToLeft),
)

Monitoring nodes that share resources ¶

Sometimes, you want a group of children nodes to interact between each other via some shared resource that only the workers know about (for example, a gochan, a db datapool, etc).

You are able to specify a custom function (BuildNodesFn) that allocates and releases these resources.

This function should return:

* The children nodes of the supervision tree

* A function that cleans up the allocated resources (CleanupResourcesFn)

* An error, but only in the scenario where a resource initialization failed

Example:

cap.NewSupervisorSpec("root",

  // (1)
  // Implement a function that return all nodes to be supervised.
  // When this supervisor gets (re)started, this function will be called.
  // Imagine this function as a factory for it's children.
  func() ([]cap.Node, cap.CleanupResourcesFn, error) {

    // In this example, child nodes have a shared resource (a gochan)
    // and it gets passed to their constructors.
    buffer := make(chan MyType)
    nodes := []cap.Node{
      producerWorker(buffer),
      consumerWorker(buffer),
    }

    // We create a function that gets executed when the supervisor
    // shuts down.
    cleanup := func() {
      close(buffer)
    }

    // We return the allocated Node records and the cleanup function
    return nodes, cleanup, nil
  },

  // (2)
  cap.WithStartOrder(cap.RightToLeft),
)

Dealing with errors ¶

Given resources can involve IO allocations, using this functionality opens the door to a few error scenarios:

1) Resource allocation returns an error

In this scenario, the supervision start procedure will fail and it will follow the regular shutdown procedure: the already started nodes will be terminated and an error will be returned immediately.

2) Resource cleanup returns an error

In this scenario, the termination procedure will collect the error and report it in the returned SupervisorError.

3) Resource allocation/cleanup hangs

This library does not handle this scenario. Is the responsibility of the user of the API to implement start timeouts and cleanup timeouts inside the given BuildNodesFn and CleanupResourcesFn functions.