README
¶
go-toil
A library that provides simple functionality for managing 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-toil
Documentation
¶
Overview ¶
Package toil provides simple functionality for managing toilers (i.e., workers).
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 me this block (i.e., not return)
// until the work is done.
}
Then create a toil.Group. For example:
var ( ToilerGroup = toil.NewGroup() )
Then register one of more toilers (i.e., types that implement the toil.Toiler interface) with the toiler group. For example:
toiler := newAwesomeToiler() ToilerGroup.Register(toiler)
Then, you can call the Toil method of the toiler group in place like main(). For example:
func main() {
// ...
// Calling the Toil() method on the toiler group
// will cause it to call the Toil() method of
// each toiler registered with it.
//
// Thus causing each of those toilers registered
// with it to start doing its work (whatever that
// happens to be) all at the same time, simultaneously.
//
// This will block until all the toilers registered
// in this toiler group's Toil() methods finishes
// (either because it returned gracefully or because
// it panic()ed).
ToilerGroup.Toil()
// ...
}
Observers ¶
A toiler's Toil method can finish in one of two ways. Either it will return gracefully, or it will panic().
The toiler group is OK with either.
But also, the toiler group provides the toiler with a convenient way of being notified of each case.
If a toiler also has a Terminated() method, then the toiler group will call the toiler's Terminated() 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) Terminated() {
//@TODO: Do something with this notification.
}
If a toiler also has a PanickedNotice() method, then the toiler group 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.
}
And of course, a toiler can take advantage of both of these notifications and have both a PanickedNotice() and Terminated() method. 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.
}
func (toiler *awesomeToiler) Terminated() {
//@TODO: Do something with this notification.
}
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Group ¶
type Group interface {
// Len returns the number of toilers registered with this Group.
Len() int
// Register registers a toiler with this Group.
Register(Toiler)
// Toil makes all the toilers registered with this Group toil (i.e., do work),
// by calling each of the registered toilers' Toil methods.
Toil()
}
Group is an interface that wraps the Len, Register and Toil methods.
type Toiler ¶
type Toiler interface {
Toil()
}
Toiler is an interface that wraps the Toil method.
The purpose of the Toil method is to do work. The Toil method should block while it is doing work.
type ToilerFunc ¶
type ToilerFunc func()
The ToilerFunc type is an adapter to allow the use of ordinary functions as toilers. If fn is a function with the appropriate signature, ToilerFunc(fn) is a Toiler that calls fn.
Example:
func fn() {
//@TODO
}
var toiler Toiler = ToilerFunc(fn)
Source Files
Directories