core

README

CN-Infra Core

The core package contains the CN-Infra Core that manages the startup and graceful shutdown of CN-Infra based applications. The startup & shutdown lifecycle is depicted in the sequence diagram below. The startup and shutdown behavior is described in comments for the Start() and Stop() functions in agent_core.go, and for the EventLoopWithInterrupt()function in event_loop.go.

The core package also defines the CN-Infra Core's SPI that must be implemented by each plugin (see Guidelines). The SPI is used by the Core to Init(), AfterInit() and Close() each plugin.

Documentation

Overview

Package core manages the lifecycle of all plugins (start, graceful shutdown) and defines the core lifecycle SPI. The core lifecycle SPI must be implemented by each plugin.

Index

• Variables
• func EventLoopWithInterrupt(agent *Agent, closeChan chan struct{}) error
• type Agent
  • func NewAgent(logger logging.Logger, maxStartup time.Duration, plugins ...*NamedPlugin) *Agent
  • func (agent *Agent) Start() error
  • func (agent *Agent) Stop() error
• type Flavor
• type NamedPlugin
  • func ListPluginsInFlavor(flavor Flavor) (plugins []*NamedPlugin)
  • func (np *NamedPlugin) String() string
• type Option
• type Plugin
• type PluginName
• type PostInit
• type WithLoggerOpt
  • func WithLogger(logger logging.Logger) *WithLoggerOpt
  • func (marker *WithLoggerOpt) OptionMarkerCore()
• type WithTimeoutOpt
  • func WithTimeout(timeout time.Duration) *WithTimeoutOpt
  • func (marker *WithTimeoutOpt) OptionMarkerCore()

Variables

var (
	BuildVersion string
	BuildDate    string
)

variables set by the Makefile using ldflags

Functions

func EventLoopWithInterrupt

func EventLoopWithInterrupt(agent *Agent, closeChan chan struct{}) error

EventLoopWithInterrupt starts an instance of the agent created with NewAgent(). Agent is stopped when <closeChan> is closed or user interrupt (SIGINT) is received.

Types

type Agent

type Agent struct {
	logging.Logger
	// contains filtered or unexported fields
}

Agent implements startup & shutdown procedures.

func NewAgent

func NewAgent(logger logging.Logger, maxStartup time.Duration, plugins ...*NamedPlugin) *Agent

NewAgent returns a new instance of the Agent with plugins. <logger> will be used to log messages related to the agent life-cycle, but not for the plugins themselves. <maxStartup> puts a time limit on initialization of all provided plugins. Agent.Start() returns ErrPluginsInitTimeout error if one or more plugins fail to initialize inside the specified time limit. <plugins> is a variable list of plugins to load. ListPluginsInFlavor() helper method can be used to obtain the list from a given flavor.

func (*Agent) Start

func (agent *Agent) Start() error

Start starts/initializes all selected plugins. The first iteration tries to run Init() method on every plugin from the list. If any of the plugins fails to initialize (Init() return non-nil error), initialization is cancelled by calling Close() method for already initialized plugins in the reverse order. The encountered error is returned by this function as-is. The second iteration does the same for the AfterInit() method. The difference is that AfterInit() is an optional method (not required by the Plugin interface, only suggested by PostInit interface) and therefore not necessarily called on every plugin. The startup/initialization must take no longer than maxStartup time limit, otherwise ErrPluginsInitTimeout error is returned.

func (*Agent) Stop

func (agent *Agent) Stop() error

Stop gracefully shuts down the Agent. It is called usually when the user interrupts the Agent from the EventLoopWithInterrupt().

This implementation tries to call Close() method on every plugin on the list in the reverse order. It continues even if some error occurred.

type Flavor

type Flavor interface {
	// Plugins returns list of plugins.
	// Name of the plugin is supposed to be related to field name of Flavor struct
	Plugins() []*NamedPlugin

	// Inject method is supposed to be implemented by each Flavor
	// to inject dependencies between the plugins.
	// When this method is called for the first time it returns true
	// (meaning the dependency injection ran at the first time).
	// It is possible to call this method repeatedly (then it will return false).
	Inject() (firstRun bool)

	// LogRegistry is a getter for accessing log registry (that allows to create new loggers)
	LogRegistry() logging.Registry
}

Flavor is structure that contains a particular combination of plugins (fields of plugins)

type NamedPlugin

type NamedPlugin struct {
	PluginName
	Plugin
}

NamedPlugin represents a Plugin with a name

func ListPluginsInFlavor

func ListPluginsInFlavor(flavor Flavor) (plugins []*NamedPlugin)

ListPluginsInFlavor lists plugins in a Flavor. It extracts all plugins and returns them as a slice of NamedPlugins.

func (*NamedPlugin) String

func (np *NamedPlugin) String() string

String returns the PluginName

type Option

type Option interface {
	//OptionMarkerCore is just for marking implementation that it implements this interface
	OptionMarkerCore()
}

Option defines the maximum time that is attempted to deliver notification.

type Plugin

type Plugin interface {
	// Init is called in the agent startup phase.
	Init() error
	// Close is called in the agent cleanup phase.
	Close() error
}

Plugin interface defines plugin's basic life-cycle methods.

type PluginName

type PluginName string

PluginName is a part of the plugin's API and it is supposed to be defined as a publicly accessible string constant. It is used to obtain the appropriate instance of the registry (there are multiple instances).

type PostInit

type PostInit interface {
	// AfterInit is called once Init() of all plugins have returned without error.
	AfterInit() error
}

PostInit interface defines optional method for plugins with complex initialization.

type WithLoggerOpt

type WithLoggerOpt struct {
	Logger logging.Logger
}

WithLoggerOpt defines a logger that logs if delivery of notification is unsuccessful.

func WithLogger

func WithLogger(logger logging.Logger) *WithLoggerOpt

WithLogger creates an option for ToChan function that specifies a logger to be used.

func (*WithLoggerOpt) OptionMarkerCore

func (marker *WithLoggerOpt) OptionMarkerCore()

OptionMarkerCore is just for marking implementation that it implements this interface

type WithTimeoutOpt

type WithTimeoutOpt struct {
	Timeout time.Duration
}

WithTimeoutOpt defines the maximum time that is attempted to deliver notification.

func WithTimeout

func WithTimeout(timeout time.Duration) *WithTimeoutOpt

WithTimeout creates an option for ToChan function that defines a timeout for notification delivery.

func (*WithTimeoutOpt) OptionMarkerCore

func (marker *WithTimeoutOpt) OptionMarkerCore()

OptionMarkerCore is just for marking implementation that it implements this interface