kernel

package
v0.26.2 Latest Latest
Warning

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

Go to latest
Published: Oct 11, 2024 License: MIT Imports: 22 Imported by: 0

Documentation

Index

Constants

View Source
const (
	ExitCodeOk           = 0
	ExitCodeErr          = 1
	ExitCodeNothingToRun = 10
	ExitCodeNoForeground = 11
	ExitCodeForced       = 12
)
View Source
const (
	// The kernel is split into three stages.
	//  * Essential: Starts first and shuts down last. Includes metric writers and anything else that gets data from other
	//    modules and must not exist before the other modules do so.
	//  * Service: Contains services provided to the application that should start first but still depend on the essential
	//    modules. This includes the modules provided by gosoline, for example the ApiServer.
	//  * Application: Your code should normally run in this stage. It will be started after other services are already
	//    running and shut down first so other stages still have some time to process the messages they did receive from
	//    your application.
	StageEssential   = common.StageEssential
	StageService     = common.StageService
	StageApplication = common.StageApplication
)

Variables

View Source
var ErrKernelStopping = fmt.Errorf("stopping kernel")

Functions

func BuildFactory

func BuildFactory(ctx context.Context, config cfg.Config, logger log.Logger, options []Option) (*factory, error)

func NewBlueprint

func NewBlueprint(options ...Option) *blueprint

func NewFactory

func NewFactory(ctx context.Context, config cfg.Config, logger log.Logger, bp *blueprint) (*factory, error)

Types

type ApplicationStage

type ApplicationStage struct{}

func (ApplicationStage) GetStage

func (s ApplicationStage) GetStage() int

type BackgroundModule

type BackgroundModule struct{}

A BackgroundModule has no effect on application termination. If you only have running background modules, the application will exit regardless.

func (BackgroundModule) IsBackground

func (m BackgroundModule) IsBackground() bool

func (BackgroundModule) IsEssential

func (m BackgroundModule) IsEssential() bool

type DefaultModule

type DefaultModule struct {
	ForegroundModule
	ApplicationStage
}

The DefaultModule type you could use for your application code. Your module will

  • Run at the application stage
  • Be a foreground module and can therefore shut down the kernel if you don't run other foreground modules
  • Implement any future methods we might add to the Module interface with some reasonable default values

type EssentialBackgroundModule

type EssentialBackgroundModule struct{}

An EssentialBackgroundModule is similar to an essential module, but it will not cause the kernel to continue running if only this module remains. From the previous example the database might be a good candidate - the app can't run without the database, but a database alone also is no proper app. The ProducerDaemon is using this module for example.

func (EssentialBackgroundModule) IsBackground

func (m EssentialBackgroundModule) IsBackground() bool

func (EssentialBackgroundModule) IsEssential

func (m EssentialBackgroundModule) IsEssential() bool

type EssentialModule

type EssentialModule struct{}

An EssentialModule will cause the application to exit as soon as the first essential module stops running. For example, if you have a web server with a database and API as essential modules the application would exit as soon as either the database is shut down or the API is stopped. In both cases there is no point in running the rest anymore as the main function of the web server can no longer be fulfilled.

func (EssentialModule) IsBackground

func (m EssentialModule) IsBackground() bool

func (EssentialModule) IsEssential

func (m EssentialModule) IsEssential() bool

type EssentialStage

type EssentialStage struct{}

func (EssentialStage) GetStage

func (s EssentialStage) GetStage() int

type ExitHandler

type ExitHandler func(code int)

type ForegroundModule

type ForegroundModule struct{}

A ForegroundModule will cause the application to exit as soon as the last foreground module exited. For example, if you have three tasks you have to perform and afterwards want to terminate the program, simply declare all three as foreground modules.

func (ForegroundModule) IsBackground

func (m ForegroundModule) IsBackground() bool

func (ForegroundModule) IsEssential

func (m ForegroundModule) IsEssential() bool

type FullModule

type FullModule interface {
	Module
	TypedModule
	StagedModule
	HealthCheckedModule
}

A FullModule provides all the methods a module can have and thus never relies on defaults.

type HealthCheckResult added in v0.10.0

type HealthCheckResult []ModuleHealthCheckResult

func (HealthCheckResult) Err added in v0.10.0

func (r HealthCheckResult) Err() error

func (HealthCheckResult) GetUnhealthy added in v0.10.0

func (r HealthCheckResult) GetUnhealthy() HealthCheckResult

func (HealthCheckResult) GetUnhealthyNames added in v0.10.0

func (r HealthCheckResult) GetUnhealthyNames() []string

func (HealthCheckResult) IsHealthy added in v0.10.0

func (r HealthCheckResult) IsHealthy() bool

type HealthCheckSettings added in v0.10.0

type HealthCheckSettings struct {
	Timeout      time.Duration `cfg:"timeout" default:"1m"`
	WaitInterval time.Duration `cfg:"wait_interval" default:"3s"`
}

type HealthCheckedModule added in v0.10.0

type HealthCheckedModule interface {
	IsHealthy(ctx context.Context) (bool, error)
}

A HealthCheckedModule provides an interface to implement a health check for a module. This health check is used to determine if the module is in a ready state after executing its run method and afterwards to check for the overall application healthyness.

type HealthChecker added in v0.10.0

type HealthChecker func() HealthCheckResult

func GetHealthChecker added in v0.10.0

func GetHealthChecker(ctx context.Context) (HealthChecker, error)

type Kernel

type Kernel interface {
	HealthCheck() HealthCheckResult
	Running() <-chan struct{}
	Run()
	Stop(reason string)
}

func BuildKernel

func BuildKernel(ctx context.Context, config cfg.Config, logger log.Logger, options []Option) (Kernel, error)

type Middleware

type Middleware func(next MiddlewareHandler) MiddlewareHandler

type MiddlewareFactory

type MiddlewareFactory func(ctx context.Context, config cfg.Config, logger log.Logger) (Middleware, error)

func BuildSimpleMiddleware

func BuildSimpleMiddleware(handler func(next MiddlewareHandler)) MiddlewareFactory

type MiddlewareHandler

type MiddlewareHandler func()

type Module

type Module interface {
	// Run the module. If the provided context is canceled you have a few seconds (configurable with kernel.killTimeout)
	// until your module is killed (via exit(1)). If you return from Run, it is assumed that your module is done
	// executing and (depending on the type of your module) this might trigger a kernel shutdown.
	// If one of your modules returns an error, the kernel will stop (thus stopping all other modules).
	Run(ctx context.Context) error
}

A Module provides a single function or service for your application. For example, an HTTP server would be a single module (see "httpserver") while a daemon writing metrics in the background would be a separate module (see "log").

func NewModuleFunc

func NewModuleFunc(run ModuleRunFunc) Module

type ModuleFactory

type ModuleFactory func(ctx context.Context, config cfg.Config, logger log.Logger) (Module, error)

type ModuleHealthCheckResult added in v0.10.0

type ModuleHealthCheckResult struct {
	StageIndex int
	Name       string
	Healthy    bool
	Err        error
}

type ModuleMultiFactory

type ModuleMultiFactory func(ctx context.Context, config cfg.Config, logger log.Logger) (map[string]ModuleFactory, error)

type ModuleOption

type ModuleOption func(ms *moduleConfig)

func MergeOptions

func MergeOptions(options []ModuleOption) ModuleOption

Combine a list of options by applying them in order.

func ModuleStage

func ModuleStage(moduleStage int) ModuleOption

Overwrite the stage of a module. Using this, you can move a module of yours (or someone else) to a different stage, e.g. to make sure it shuts down after another module (because it is the consumer of another module and you need the other module to stop producing before you can stop consuming).

func ModuleType

func ModuleType(moduleTypeProvider func() TypedModule) ModuleOption

Overwrite the type a module specifies by something else. E.g., if you have a background module you completely depend on, you can do

k.Add("your module", NewYourModule(), kernel.ModuleType(kernel.TypeEssential))

to declare the module as essential. Now if the module quits the kernel will shut down instead of continuing to run.

type ModuleRunFunc

type ModuleRunFunc func(ctx context.Context) error

type Option

type Option func(bp *blueprint)

func WithExitHandler

func WithExitHandler(handler func(code int)) Option

func WithKillTimeout

func WithKillTimeout(killTimeout time.Duration) Option

func WithMiddlewareFactory

func WithMiddlewareFactory(factory MiddlewareFactory, position Position) Option

func WithModuleFactory

func WithModuleFactory(name string, factory ModuleFactory, options ...ModuleOption) Option

func WithModuleMultiFactory

func WithModuleMultiFactory(factory ModuleMultiFactory) Option

type Position

type Position string
const (
	PositionBeginning Position = "beginning"
	PositionEnd       Position = "end"
)

type ServiceStage

type ServiceStage struct{}

func (ServiceStage) GetStage

func (s ServiceStage) GetStage() int

type Settings added in v0.10.0

type Settings struct {
	KillTimeout time.Duration       `cfg:"kill_timeout" default:"10s"`
	HealthCheck HealthCheckSettings `cfg:"health_check"`
}

type StagedModule

type StagedModule interface {
	GetStage() int
}

A module can be associated with a stage describing in which order to boot and invoke different modules. Modules with a smaller stage index are booted sooner and shut down later. You should use the StageEssential, StageService and StageApplication constants unless you have very specific needs and know what you are doing.

type TypedModule

type TypedModule interface {
	IsEssential() bool
	IsBackground() bool
}

TypedModule denotes a module that knows whether it is essential and whether it runs in the foreground or background. If your module is essential, the kernel will shut down after your module stopped. If your module is a background module, it will not keep the kernel running. Thus, an essential background module will kill the kernel if it stops, but it will not keep the kernel from stopping. An example would be the producer daemon, which should not stop, but won't do much good alone. If you don't implement TypedModule it will default to a non-essential foreground module.

func TypeBackground

func TypeBackground() TypedModule

func TypeEssential

func TypeEssential() TypedModule

func TypeEssentialBackground

func TypeEssentialBackground() TypedModule

func TypeForeground

func TypeForeground() TypedModule

Directories

Path Synopsis

Jump to

Keyboard shortcuts

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