run

Documentation

Overview

Package run implements a lifecycle framework to control modules.

Index

• type Bytes
  • func (b *Bytes) Set(s string) error
  • func (b Bytes) String() string
  • func (b *Bytes) Type() string
• type ChannelCloser
  • func NewChannelCloser() *ChannelCloser
  • func (c *ChannelCloser) AddReceiver() bool
  • func (c *ChannelCloser) AddSender() bool
  • func (c *ChannelCloser) CloseNotify() <-chan struct{}
  • func (c *ChannelCloser) CloseThenWait()
  • func (c *ChannelCloser) Closed() bool
  • func (c *ChannelCloser) ReceiverDone()
  • func (c *ChannelCloser) SenderDone()
• type ChannelGroupCloser
  • func NewChannelGroupCloser(closer ...*ChannelCloser) *ChannelGroupCloser
  • func (c *ChannelGroupCloser) CloseThenWait()
  • func (c *ChannelGroupCloser) Closed() bool
• type Closer
  • func NewCloser(initial int) *Closer
  • func (c *Closer) AddRunning() bool
  • func (c *Closer) CloseNotify() <-chan struct{}
  • func (c *Closer) CloseThenWait()
  • func (c *Closer) Closed() bool
  • func (c *Closer) Ctx() context.Context
  • func (c *Closer) Done()
• type Config
• type FlagSet
  • func NewFlagSet(name string) *FlagSet
• type Group
  • func NewGroup(name string) Group
  • func (g *Group) Deregister(units ...Unit) []bool
  • func (g Group) ListUnits() string
  • func (g Group) Name() string
  • func (g *Group) Register(units ...Unit) []bool
  • func (g *Group) RegisterFlags() *FlagSet
  • func (g *Group) Run(ctx context.Context) (err error)
  • func (g *Group) RunConfig() (interrupted bool, err error)
  • func (g *Group) WaitTillReady()
• type PreRunner
• type Role
• type Service
• type StopNotify
• type Unit
  • func NewTester(id string) (Unit, func())

Types

type Bytes

type Bytes int64

Bytes is a custom type to store memory size in bytes.

func (*Bytes) Set

func (b *Bytes) Set(s string) error

Set sets the Bytes value from the input string.

func (Bytes) String

func (b Bytes) String() string

String returns a string representation of the Bytes value.

func (*Bytes) Type

func (b *Bytes) Type() string

Type returns the type name of the Bytes custom type.

type ChannelCloser

type ChannelCloser struct {
	// contains filtered or unexported fields
}

ChannelCloser can close a goroutine then wait for it to stop.

func NewChannelCloser

func NewChannelCloser() *ChannelCloser

NewChannelCloser instances a new ChannelCloser.

func (*ChannelCloser) AddReceiver

func (c *ChannelCloser) AddReceiver() bool

AddReceiver adds a running receiver.

func (*ChannelCloser) AddSender

func (c *ChannelCloser) AddSender() bool

AddSender adds a running sender.

func (*ChannelCloser) CloseNotify

func (c *ChannelCloser) CloseNotify() <-chan struct{}

CloseNotify receives a signal from Close.

func (*ChannelCloser) CloseThenWait

func (c *ChannelCloser) CloseThenWait()

CloseThenWait closes all tasks then waits till they are done.

func (*ChannelCloser) Closed

func (c *ChannelCloser) Closed() bool

Closed returns whether the ChannelCloser is closed.

func (*ChannelCloser) ReceiverDone

func (c *ChannelCloser) ReceiverDone()

ReceiverDone notifies that receiver task is done.

func (*ChannelCloser) SenderDone

func (c *ChannelCloser) SenderDone()

SenderDone notifies that running sender is done.

type ChannelGroupCloser

type ChannelGroupCloser struct {
	// contains filtered or unexported fields
}

ChannelGroupCloser can close a goroutine group then wait for it to stop.

func NewChannelGroupCloser

func NewChannelGroupCloser(closer ...*ChannelCloser) *ChannelGroupCloser

NewChannelGroupCloser instances a new ChannelGroupCloser.

func (*ChannelGroupCloser) CloseThenWait

func (c *ChannelGroupCloser) CloseThenWait()

CloseThenWait closes all closer then waits till they are done.

func (*ChannelGroupCloser) Closed

func (c *ChannelGroupCloser) Closed() bool

Closed returns whether the ChannelGroupCloser is closed.

type Closer

type Closer struct {
	// contains filtered or unexported fields
}

Closer can close a goroutine then wait for it to stop.

func NewCloser

func NewCloser(initial int) *Closer

NewCloser instances a new Closer.

func (*Closer) AddRunning

func (c *Closer) AddRunning() bool

AddRunning adds a running task.

func (*Closer) CloseNotify

func (c *Closer) CloseNotify() <-chan struct{}

CloseNotify receives a signal from Close.

func (*Closer) CloseThenWait

func (c *Closer) CloseThenWait()

CloseThenWait closes all tasks then waits till they are done.

func (*Closer) Closed

func (c *Closer) Closed() bool

Closed returns whether the Closer is closed.

func (*Closer) Ctx

func (c *Closer) Ctx() context.Context

Ctx returns the context of the Closer.

func (*Closer) Done

func (c *Closer) Done()

Done notifies that one task is done.

type Config

type Config interface {
	// Unit for Group registration and identification
	Unit
	// FlagSet returns an object's FlagSet
	FlagSet() *FlagSet
	// Validate checks an object's stored values
	Validate() error
}

Config interface should be implemented by Group Unit objects that manage their own configuration through the use of flags. If a Unit's Validate returns an error it will stop the Group immediately.

type FlagSet

type FlagSet struct {
	*pflag.FlagSet
	Name string
}

FlagSet holds a pflag.FlagSet as well as an exported Name variable for allowing improved help usage information.

func NewFlagSet

func NewFlagSet(name string) *FlagSet

NewFlagSet returns a new FlagSet for usage in Config objects.

type Group

type Group struct {
	// contains filtered or unexported fields
}

Group builds on https://github.com/oklog/run to provide a deterministic way to manage service lifecycles. It allows for easy composition of elegant monoliths as well as adding signal handlers, metrics services, etc.

func NewGroup

func NewGroup(name string) Group

NewGroup return a Group with input name.

func (*Group) Deregister

func (g *Group) Deregister(units ...Unit) []bool

Deregister will remove the provided objects implementing the Unit interface from the Group. The returned array of booleans is of the same size as the amount of provided Units, signaling for each provided Unit if it successfully deregistered from Group or if it was ignored.

func (Group) ListUnits

func (g Group) ListUnits() string

ListUnits returns a list of all Group phases and the Units registered to each of them.

func (Group) Name

func (g Group) Name() string

Name shows the name of the group.

func (*Group) Register

func (g *Group) Register(units ...Unit) []bool

Register will inspect the provided objects implementing the Unit interface to see if it needs to register the objects for any of the Group bootstrap phases. If a Unit doesn't satisfy any of the bootstrap phases it is ignored by Group. The returned array of booleans is of the same size as the amount of provided Units, signaling for each provided Unit if it successfully registered with Group for at least one of the bootstrap phases or if it was ignored.

func (*Group) RegisterFlags

func (g *Group) RegisterFlags() *FlagSet

RegisterFlags returns FlagSet contains Flags in all modules.

func (*Group) Run

func (g *Group) Run(ctx context.Context) (err error)

Run will execute all phases of all registered Units and block until an error occurs. If RunConfig has been called prior to Run, the Group's Config phase will be skipped and Run continues with the PreRunner and Service phases.

The following phases are executed in the following sequence:

Config phase (serially, in order of Unit registration)
  - FlagSet()        Get & register all FlagSets from Config Units.
  - Flag Parsing     Using the provided args (os.Args if empty)
  - Validate()       Validate Config Units. Exit on first error.

PreRunner phase (serially, in order of Unit registration)
  - PreRun(ctx context.Context)         Execute PreRunner Units. Exit on first error.

Service phase (concurrently)
  - Serve()          Execute all Service Units in separate Go routines.
  - Wait             Block until one of the Serve() methods returns
  - GracefulStop()   Call interrupt handlers of all Service Units.

Run will return with the originating error on:
- first Config.Validate()  returning an error
- first PreRunner.PreRun(ctx context.Context) returning an error
- first Service.Serve()    returning (error or nil)

func (*Group) RunConfig

func (g *Group) RunConfig() (interrupted bool, err error)

RunConfig runs the Config phase of all registered Config aware Units. Only use this function if needing to add additional wiring between config and (pre)run phases and a separate PreRunner phase is not an option. In most cases it is best to use the Run method directly as it will run the Config phase prior to executing the PreRunner and Service phases. If an error is returned the application must shut down as it is considered fatal.

func (*Group) WaitTillReady

func (g *Group) WaitTillReady()

WaitTillReady blocks the goroutine till all modules are ready.

type PreRunner

type PreRunner interface {
	// Unit for Group registration and identification
	Unit
	PreRun(context.Context) error
}

PreRunner interface should be implemented by Group Unit objects that need a pre run stage before starting the Group Services. If a Unit's PreRun returns an error it will stop the Group immediately.

type Role

type Role interface {
	Role() databasev1.Role
}

Role is an interface that should be implemented by Group Unit objects that need to be able to return their Role.

type Service

type Service interface {
	// Unit for Group registration and identification
	Unit
	// Serve starts the GroupService and blocks.
	Serve() StopNotify
	// GracefulStop shuts down and cleans up the GroupService.
	GracefulStop()
}

Service interface should be implemented by Group Unit objects that need to run a blocking service until an error occurs or a shutdown request is made. The Serve method must be blocking and return an error on unexpected shutdown. Recoverable errors need to be handled inside the service itself. GracefulStop must gracefully stop the service and make the Serve call return.

Since Service is managed by Group, it is considered a design flaw to call any of the Service methods directly in application code.

type StopNotify

type StopNotify <-chan struct{}

StopNotify sends the stopped event to the running system.

type Unit

type Unit interface {
	Name() string
}

Unit is the default interface an object needs to implement for it to be able to register with a Group. Name should return a short but good identifier of the Unit.

func NewTester

func NewTester(id string) (Unit, func())

NewTester return a tester module to stop the runtime programmatically.