Documentation
¶
Index ¶
- Variables
- func GetNodeName(ctx context.Context) (string, bool)
- func WithoutCancel(ctx context.Context) context.Context
- type Child
- type ChildNotification
- type 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
- type NotifyStartFn
- type Opt
- type Restart
- type Shutdown
- type ShutdownTag
Constants ¶
This section is empty.
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 ¶
GetNodeName gets a capataz worker name from a context
Types ¶
type Child ¶
type Child struct {
// contains filtered or unexported fields
}
Child is the runtime representation of a Spec
func (Child) GetRuntimeName ¶
GetRuntimeName returns the name of this child (once started). It will have a prefix with the supervisor name
func (Child) Terminate ¶
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 ¶
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 ¶
DoesCapturePanic indicates if this child handles panics
func (ChildSpec) GetRestart ¶
GetRestart returns the Restart setting for this ChildSpec
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
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 ¶
WithCapturePanic specifies if panics raised by this worker should be treated as errors. restartable errors.
func WithRestart ¶
WithRestart specifies how the parent supervisor should restart this worker after an error is encountered.
func WithShutdown ¶
WithShutdown specifies how the shutdown of the worker is going to be handled. Read `Indefinitely` and `Timeout` shutdown values documentation for details.
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 )
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 ¶
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
Source Files