README
¶
go-retoil
A library that provides simple functionality for restarting toilers (i.e., workers) for the Go programming language.
Documention
Online documentation, which includes examples, can be found at: http://godoc.org/github.com/reiver/go-retoil
Documentation
¶
Overview ¶
Package retoil provides simple functionality for restarting toilers (i.e., workers).
A toiler that has a Toil() method, that does work, blocks (i.e., doesn't return) until the work is done, and panic()s if there is a problem it cannot or doesn't want to deal with.
Usage ¶
To use, create one or more types that implement the toil.Toiler interface. For example:
type awesomeToiler struct{}
func newAwesomeToiler() {
toiler := awesomeToiler{}
return &toiler
}
func (toiler *awesomeToiler) Toil() {
//@TODO: Do work here.
//
// And this blocks (i.e., not not return)
// until the work is done.
//
// It also panic()s if it encounters a problem
// it cannot or doesn't want to deal with.
}
Then create a retoiler that wraps that toiler. (Also choosing a retoil strategy, when doing that.)
toiler := newAwesomeToiler() strategizer := DelayedLimitedStrategy(16, 5 * time.Second) //strategizer := LimitedExponentialBackoffStrategy(16, 5 * time.Second) retoiler := retoil.New(toiler, strategizer)
Observers ¶
A toiler's Toil method can finish in one of two ways. Either it will return gracefully, or it will panic().
The retoiler is OK with either.
But also, the retoiler provides the toiler with a convenient way of being notified of each case.
If a toiler also has a ReturnedNotice() method, then the retoiler will call the toiler's ReturnedNotice() method when the toiler's Toil() method has returned gracefully. For example:
type awesomeToiler struct{}
func newAwesomeToiler() {
toiler := awesomeToiler{}
return &toiler
}
func (toiler *awesomeToiler) Toil() {
//@TODO: Do work here.
}
func (toiler *awesomeToiler) ReturnedNotice() {
//@TODO: Do something with this notification.
}
If a toiler also has a PanickedNotice() method, then the retoiler will call the toiler's PanickedNotice() method when the toiler's Toil() method has panic()ed. For example:
type awesomeToiler struct{}
func newAwesomeToiler() {
toiler := awesomeToiler{}
return &toiler
}
func (toiler *awesomeToiler) Toil() {
//@TODO: Do work here.
}
func (toiler *awesomeToiler) PanickedNotice() {
//@TODO: Do something with this notification.
}
If a toiler also has a RecoveredNotice() method, then the retoiler will call the toiler's RecoveredNotice() method when the toiler's Toil() method has restarted after a panic(). For example:
type awesomeToiler struct{}
func newAwesomeToiler() {
toiler := awesomeToiler{}
return &toiler
}
func (toiler *awesomeToiler) Toil() {
//@TODO: Do work here.
}
func (toiler *awesomeToiler) RecoveredNotice() {
//@TODO: Do something with this notification.
}
And of course, a toiler can take advantage of both of these notifications and have both a ReturnedNotice(), PanickedNotice() and RecoveredNotice() method. For example:
type awesomeToiler struct{}
func newAwesomeToiler() {
toiler := awesomeToiler{}
return &toiler
}
func (toiler *awesomeToiler) Toil() {
//@TODO: Do work here.
}
func (toiler *awesomeToiler) ReturnedNotice() {
//@TODO: Do something with this notification.
}
func (toiler *awesomeToiler) PanickedNotice() {
//@TODO: Do something with this notification.
}
func (toiler *awesomeToiler) RecoveredNotice() {
//@TODO: Do something with this notification.
}
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func New ¶
func New(toiler toil.Toiler, strategizer Strategizer) toil.Toiler
New returns an initialized retoiler (which is also a toil.Toiler), based on the toiler and strategizer passed as parameters.
Types ¶
type Strategizer ¶
type Strategizer interface {
// MayPanickedRetoil will be asked by a retoiler if it may retoil after a the toiler panic()ed.
MayPanickedRetoil(interface{}) bool
// MayReturnedRetoil will be asked by a retoiler if it may retoil after a the toiler returned (gracefully).
MayReturnedRetoil() bool
}
func DelayedLimitedStrategy ¶
func DelayedLimitedStrategy(maxRetoils uint, delay time.Duration) Strategizer
DelayedLimitedStrategy returns an initialized retoil.Strategizer which will only cause a retoil on a panic() (and not on a return) at most 'maxRetoils' times with at least a delay of 'delay' between each retoil.
func LimitedExponentialBackoffStrategy ¶
func LimitedExponentialBackoffStrategy(maxRetoils uint, timeResolution time.Duration) Strategizer
LimitedExponentialBackoffStrategy returns an initialized retoil.Strategizer which will only cause a retoil on a panic() (and not on a return) at most 'maxRetoils' times with using exponential backoff with time resolution 'timeResolution' to decide the delay between each retoil.
func NeverStrategy ¶
func NeverStrategy() Strategizer
NeverStrategy returns an initialized retoil.Strategizer which will never allow a retoil.
Source Files