run

package
v0.11.0 Latest Latest
Warning

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

 Go to latest Published: Aug 24, 2026 License: Apache-2.0 Imports: 20 Imported by: 0

Documentation

Overview

Package run implements a lifecycle framework to control modules.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func GoWithSignal added in v0.11.0 

func GoWithSignal[T any](ctx context.Context, component string, log *logger.Logger, fn func(context.Context) T, opts ...Option) <-chan SignalResult[T]

GoWithSignal launches fn with recovery and sends one SignalResult, then closes the buffered channel. Use it when select logic needs both value and panic outcome in-band.

Types

type Bytes added in v0.4.0 

type Bytes int64

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

func (*Bytes) Set added in v0.4.0 

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

Set sets the Bytes value from the input string.

func (Bytes) String added in v0.4.0 

func (b Bytes) String() string

String returns a string representation of the Bytes value.

func (*Bytes) Type added in v0.4.0 

func (b *Bytes) Type() string

Type returns the type name of the Bytes custom type.

type ChannelCloser added in v0.5.0 

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

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

func NewChannelCloser added in v0.5.0 

func NewChannelCloser() *ChannelCloser

NewChannelCloser instances a new ChannelCloser.

func (*ChannelCloser) AddReceiver added in v0.5.0 

func (c *ChannelCloser) AddReceiver() bool

AddReceiver adds a running receiver.

func (*ChannelCloser) AddSender added in v0.5.0 

func (c *ChannelCloser) AddSender() bool

AddSender adds a running sender.

func (*ChannelCloser) Close added in v0.11.0 

func (c *ChannelCloser) Close()

Close notifies all tasks to stop and prevents new tasks from being added.

func (*ChannelCloser) CloseNotify added in v0.5.0 

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

CloseNotify receives a signal from Close.

func (*ChannelCloser) CloseThenWait added in v0.5.0 

func (c *ChannelCloser) CloseThenWait()

CloseThenWait closes all tasks then waits till they are done.

func (*ChannelCloser) Closed added in v0.5.0 

func (c *ChannelCloser) Closed() bool

Closed returns whether the ChannelCloser is closed.

func (*ChannelCloser) Ctx added in v0.11.0 

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

Ctx returns the lifecycle context owned by the ChannelCloser.

func (*ChannelCloser) ReceiverDone added in v0.5.0 

func (c *ChannelCloser) ReceiverDone()

ReceiverDone notifies that receiver task is done.

func (*ChannelCloser) SenderDone added in v0.5.0 

func (c *ChannelCloser) SenderDone()

SenderDone notifies that running sender is done.

func (*ChannelCloser) Wait added in v0.11.0 

func (c *ChannelCloser) Wait()

Wait waits until all senders and receivers are done.

type ChannelGroupCloser added in v0.5.0 

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

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

func NewChannelGroupCloser added in v0.5.0 

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

NewChannelGroupCloser instances a new ChannelGroupCloser.

func (*ChannelGroupCloser) CloseThenWait added in v0.5.0 

func (c *ChannelGroupCloser) CloseThenWait()

CloseThenWait closes all closer then waits till they are done.

func (*ChannelGroupCloser) Closed added in v0.5.0 

func (c *ChannelGroupCloser) Closed() bool

Closed returns whether the ChannelGroupCloser is closed.

type Closer added in v0.3.0 

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

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

func NewCloser added in v0.3.0 

func NewCloser(initial int) *Closer

NewCloser instances a new Closer.

func (*Closer) AddRunning added in v0.3.0 

func (c *Closer) AddRunning() bool

AddRunning adds a running task.

func (*Closer) CloseNotify added in v0.3.0 

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

CloseNotify receives a signal from Close.

func (*Closer) CloseThenWait added in v0.3.0 

func (c *Closer) CloseThenWait()

CloseThenWait closes all tasks then waits till they are done.

func (*Closer) Closed added in v0.3.0 

func (c *Closer) Closed() bool

Closed returns whether the Closer is closed.

func (*Closer) Ctx added in v0.5.0 

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

Ctx returns the context of the Closer.

func (*Closer) Done added in v0.3.0 

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 added in v0.2.0 

func NewGroup(name string) Group

NewGroup return a Group with input name.

func (*Group) Deregister added in v0.5.0 

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 Option added in v0.11.0 

type Option func(*goConfig)

Option configures Go, GoOrDie, or GoWithSignal.

func WithArtifactRoot added in v0.11.0 

func WithArtifactRoot(root string) Option

WithArtifactRoot overrides the directory that artifacts are written to.

func WithCounter added in v0.11.0 

func WithCounter(c meter.Counter) Option

WithCounter overrides the panic counter for this call. When unset, the process-wide counter from panicdiag.SetDefaultPanicCounter is used.

func WithProcessMetadata added in v0.11.0 

func WithProcessMetadata(meta map[string]string) Option

WithProcessMetadata attaches static labels to the panic record.

func WithReporter added in v0.11.0 

func WithReporter(r panicdiag.Reporter) Option

WithReporter installs a non-blocking per-call reporter for recovered panics.

func WithStateDumper added in v0.11.0 

func WithStateDumper(d panicdiag.StateDumper) Option

WithStateDumper attaches a StateDumper that runs during recovery to capture a bounded snapshot of caller-defined state alongside the panic record.

func WithStateLimitBytes added in v0.11.0 

func WithStateLimitBytes(n int64) Option

WithStateLimitBytes caps the size of the deep state dump.

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 added in v0.5.0 

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 SignalResult added in v0.11.0 

type SignalResult[T any] struct {
	Outcome *panicdiag.RecoveryOutcome
	Value   T
}

SignalResult bundles fn's typed return with the recovery outcome so the parent receives both on a single channel. Value is the zero value of T when Outcome.Panicked is true (fn never returned). Outcome is always non-nil.

type StopNotify 

type StopNotify <-chan struct{}

StopNotify sends the stopped event to the running system.

type Task added in v0.11.0 

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

Task tracks a goroutine launched by Go or GoOrDie. Done closes on exit; Outcome is nil until then.

func Go added in v0.11.0 

func Go(ctx context.Context, component string, log *logger.Logger, fn func(context.Context), opts ...Option) *Task

Go launches fn in a recovered goroutine. Panics are logged, reported, and exposed through the returned Task. Use GoOrDie for fatal panics and GoWithSignal when a select needs the outcome.

func GoOrDie added in v0.11.0 

func GoOrDie(ctx context.Context, component string, log *logger.Logger, fn func(context.Context), opts ...Option) *Task

GoOrDie launches fn with recovery, then re-raises recovered panics after diagnostics and reporters complete.

func (*Task) Done added in v0.11.0 

func (t *Task) Done() <-chan struct{}

Done returns a channel closed when the goroutine launched by Go exits.

func (*Task) Outcome added in v0.11.0 

func (t *Task) Outcome() *panicdiag.RecoveryOutcome

Outcome returns the panic-recovery outcome, or nil if the goroutine has not yet exited.

func (*Task) Wait added in v0.11.0 

func (t *Task) Wait() *panicdiag.RecoveryOutcome

Wait blocks until the goroutine exits and returns the outcome.

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.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.