Documentation
¶
Overview ¶
Grouper implements process orcestration. Runners are organized into groups, which are then organized into an execution tree. If you have modeled your subsystems as ifrit runners, startup and shutdown of your entire application can now be controlled.
Grouper provides three strategies for system startup: two static group strategies, and one DynamicGroup. Each static group strategy takes a list of members, and starts the members in the following manner:
- Parallel: all processes are started simultaneously.
- Ordered: the next process is started when the previous is ready.
The DynamicGroup allows up to N processes to be run concurrently. The dynamic group runs indefinitely until it is closed or signaled. The DynamicGroup provides a DynamicClient to allow interacting with the group. A dynamic group has the following properties:
- A dynamic group allows Members to be inserted until it is closed.
- A dynamic group can be manually closed via it's client.
- A dynamic group is automatically closed once it is signaled.
- Once a dynamic group is closed, it acts like a static group.
Groups can optionally be configured with a termination signal, and all groups have the same signaling and shutdown properties:
- The group propogates all received signals to all running members.
- If a member exits before being signaled, the group propogates the termination signal. A nil termination signal is not propogated.
Index ¶
- func NewOrdered(terminationSignal os.Signal, members Members) ifrit.Runner
- func NewParallel(terminationSignal os.Signal, members Members) ifrit.Runner
- func NewQueueOrdered(terminationSignal os.Signal, members Members) ifrit.Runner
- type DynamicClient
- type DynamicGroup
- type EntranceEvent
- type ErrDuplicateNames
- type ErrorTrace
- type ExitEvent
- type Member
- type Members
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func NewOrdered ¶
NewOrdered starts it's members in order, each member starting when the previous becomes ready. On shutdown, it will shut the started processes down in reverse order. Use an ordered group to describe a list of dependent processes, where each process depends upon the previous being available in order to function correctly.
func NewParallel ¶
NewParallel starts it's members simultaneously. Use a parallel group to describe a set of concurrent but independent processes.
func NewQueueOrdered ¶
NewQueuedOrdered starts its members in order, each member starting when the previous becomes ready. On shutdown however, unlike the ordered group, it shuts the started processes down in forward order.
Types ¶
type DynamicClient ¶
type DynamicClient interface {
/*
EntranceListener provides a new buffered channel of entrance events, which are
emited every time an inserted process is ready. To help prevent race conditions,
every new channel is populated with previously emited events, up to it's buffer
size.
*/
EntranceListener() <-chan EntranceEvent
/*
ExitListener provides a new buffered channel of exit events, which are emited
every time an inserted process exits. To help prevent race conditions, every
new channel is populated with previously emited events, up to it's buffer size.
*/
ExitListener() <-chan ExitEvent
/*
CloseNotifier provides a new unbuffered channel, which will emit a single event
once the group has been closed.
*/
CloseNotifier() <-chan struct{}
/*
Inserter provides an unbuffered channel for adding members to a group. When the
group becomes full, the insert channel blocks until a running process exits.
Once the group is closed, insert channels block forever.
*/
Inserter() chan<- Member
/*
Close causes a dynamic group to become a static group. This means that no new
members may be inserted, and the group will exit once all members have
completed.
*/
Close()
Get(name string) (ifrit.Process, bool)
}
DynamicClient provides a client with group controls and event notifications. A client can use the insert channel to add members to the group. When the group becomes full, the insert channel blocks until a running process exits the group. Once there are no more members to be added, the client can close the dynamic group, preventing new members from being added.
type DynamicGroup ¶
type DynamicGroup interface {
ifrit.Runner
Client() DynamicClient
}
A DynamicGroup begins empty, and runs members as they are inserted. A dynamic group will continue to run, even when there are no members running within it, until it is signaled to stop. Once a dynamic group is signaled to stop, it will no longer accept new members, and waits for the currently running members to complete before exiting.
func NewDynamic ¶
func NewDynamic(terminationSignal os.Signal, maxCapacity int, eventBufferSize int) DynamicGroup
NewDynamic creates a DynamicGroup.
The maxCapacity argument sets the maximum number of concurrent processes.
The eventBufferSize argument sets the number of entrance and exit events to be retained by the system. When a new event listener attaches, it will receive any previously emitted events, up to the eventBufferSize. Older events will be thrown away. The event buffer is meant to be used to avoid race conditions when the total number of members is known in advance.
The signal argument sets the termination signal. If a member exits before being signaled, the group propogates the termination signal. A nil termination signal is not propogated.
type EntranceEvent ¶
An EntranceEvent occurs every time an invoked member becomes ready.
type ErrDuplicateNames ¶
type ErrDuplicateNames struct {
DuplicateNames []string
}
ErrDuplicateNames is returned to indicate two or more members with the same name were detected. Because more than one duplicate name may be detected in a single pass, ErrDuplicateNames contains a list of all duplicate names found.
func (ErrDuplicateNames) Error ¶
func (e ErrDuplicateNames) Error() string
type ErrorTrace ¶
type ErrorTrace []ExitEvent
func (ErrorTrace) Error ¶
func (trace ErrorTrace) Error() string
func (ErrorTrace) ErrorOrNil ¶
func (trace ErrorTrace) ErrorOrNil() error
Source Files