grouper

package
v0.0.0-...-7862c31 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: May 16, 2023 License: MIT Imports: 6 Imported by: 585

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

Constants

This section is empty.

Variables

This section is empty.

Functions

func NewOrdered

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

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

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.

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

type EntranceEvent struct {
	Member  Member
	Process ifrit.Process
}

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

type ExitEvent

type ExitEvent struct {
	Member Member
	Err    error
}

An ExitEvent occurs every time an invoked member exits.

type Member

type Member struct {
	Name string
	ifrit.Runner
}

A Member associates a unique name with a Runner.

type Members

type Members []Member

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

func (Members) Validate

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL