kernel

package
v0.12.0 Latest Latest
Warning

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

 Go to latest Published: Jan 4, 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 "apiserver") 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

Source Files

View all Source files

Directories

Path Synopsis

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.