ifrit: github.com/tedsuo/ifrit/grouper Index | Files

package grouper

import "github.com/tedsuo/ifrit/grouper"

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

Package Files

client.go doc.go dynamic_group.go entrance_events.go exit_events.go members.go ordered.go parallel.go queue_ordered.go sliding_buffer.go

func NewOrdered Uses

func NewOrdered(terminationSignal os.Signal, members Members) ifrit.Runner

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 Uses

func NewParallel(terminationSignal os.Signal, members Members) ifrit.Runner

NewParallel starts it's members simultaneously. Use a parallel group to describe a set of concurrent but independent processes.

func NewQueueOrdered Uses

func NewQueueOrdered(terminationSignal os.Signal, members Members) ifrit.Runner

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.

type DynamicClient Uses

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 Uses

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 Uses

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 Uses

type EntranceEvent struct {
    Member  Member
    Process ifrit.Process
}

An EntranceEvent occurs every time an invoked member becomes ready.

type ErrDuplicateNames Uses

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 Uses

func (e ErrDuplicateNames) Error() string

type ErrorTrace Uses

type ErrorTrace []ExitEvent

func (ErrorTrace) Error Uses

func (trace ErrorTrace) Error() string

func (ErrorTrace) ErrorOrNil Uses

func (trace ErrorTrace) ErrorOrNil() error

type ExitEvent Uses

type ExitEvent struct {
    Member Member
    Err    error
}

An ExitEvent occurs every time an invoked member exits.

type Member Uses

type Member struct {
    Name string
    ifrit.Runner
}

A Member associates a unique name with a Runner.

type Members Uses

type Members []Member

Members are treated as an ordered list. Member names must be unique.

func (Members) Validate Uses

func (m Members) Validate() error

Validate checks that all member names in the list are unique. It returns an error of type ErrDuplicateNames if duplicates are detected.

Package grouper imports 6 packages (graph) and is imported by 91 packages. Updated 2018-08-09. Refresh now. Tools for package owners.