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 OptionMarkerCore
  • func (marker *OptionMarkerCore) OptionMarkerCore()
• type Plugin
• type PluginName
• type PostInit
• type WithLoggerOpt
  • func WithLogger(logger logging.Logger) *WithLoggerOpt
• type WithTimeoutOpt
  • func WithTimeout(timeout time.Duration) *WithTimeoutOpt

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 the agent and waits for the channel event event. Agent is stopped when CloseChannel is closed or user interrupt (SIGINT) is received.

Types

type Agent

type Agent struct {
	// The startup/initialization must take no longer that maxStartup.
	MaxStartupTime time.Duration

	logging.Logger
	// contains filtered or unexported fields
}

Agent implements startup & shutdown procedure.

func NewAgent

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

NewAgent returns a new instance of the Agent with plugins.

func (*Agent) Start

func (agent *Agent) Start() error

Start starts/initializes all plugins on the list. First it runs Init() method among all plugins in the list Then it tries to run AfterInit() method among all plugins t hat implements this optional method. It stops when first error occurs by calling Close() method for already initialized plugins in reverse order. The startup/initialization must take no longer that maxStartup. duration otherwise error occurs.

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 revers order. It continues event 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
}

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 uses reflection to traverse top level fields of Flavor structure. 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 {
	//OptionMarkCore is just for marking implementation that it implements this interface
	OptionMarkCore()
}

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

type OptionMarkerCore

type OptionMarkerCore struct{}

OptionMarkerCore is meant for anonymous composition in With*Opt structs

func (*OptionMarkerCore) OptionMarkerCore

func (marker *OptionMarkerCore) OptionMarkerCore()

OptionMarkerCore is just for marking implementation that it implements this interface

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 define optional method for plugins with complex initialization.

type WithLoggerOpt

type WithLoggerOpt struct {
	OptionMarkerCore
	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.

type WithTimeoutOpt

type WithTimeoutOpt struct {
	OptionMarkerCore
	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.