cn-infra: Index | Files

package agent

import ""

Package agent provides the life-cycle management agent for plugins. It is intended to be used as a base point of an application used in main package.

Here is a common example usage:

func main() {
	plugin := myplugin.NewPlugin()

	a := agent.NewAgent(
	if err := a.Run(); err != nil {


There are various options available to customize agent:

Version(ver, date, id)	- sets version of the program
QuitOnClose(chan)   	- sets signal used to quit the running agent when closed
QuitSignals(signals)	- sets signals used to quit the running agent (default: SIGINT, SIGTERM)
StartTimeout(dur)   	- sets start timeout (default: 15s)
StopTimeout(dur)    	- sets stop timeout (default: 5s)

There are two options for adding plugins to the agent:

Plugins(...)	- adds just single plugins without lookup
AllPlugins(...)	- adds plugin along with all of its plugin deps


Package Files

agent.go doc.go options.go plugin_lookup.go


var (
    // BuildVersion describes version for the build. It is usually set using `git describe --always --tags --dirty`.
    BuildVersion = "v0.0.0-dev"
    // BuildDate describes time of the build.
    BuildDate string
    // CommitHash describes commit hash for the build.
    CommitHash string

Variables set by the compiler using ldflags

var (
    // DefaultStartTimeout is default timeout for starting agent
    DefaultStartTimeout = time.Second * 15
    // DefaultStopTimeout is default timeout for stopping agent
    DefaultStopTimeout = time.Second * 5

    // DumpStackTraceOnTimeout prints stack trace on timeout or agent start/stop
    DumpStackTraceOnTimeout = os.Getenv("DUMP_STACK_ON_TIMEOUT") != ""

type Agent Uses

type Agent interface {
    // Run is a blocking call which starts the agent with all of its plugins,
    // waits for a signal from OS (SIGINT, SIGTERM by default), context cancellation or
    // close of quit channel (can be set via options) and then stops the agent.
    // Returns nil if all the plugins were intialized and closed successfully.
    Run() error
    // Start starts the agent with all the plugins, calling their Init() and optionally AfterInit().
    // Returns nil if all the plugins were initialized successfully.
    Start() error
    // Stop stops the agent with all the plugins, calling their Close().
    // Returns nil if all the plugins were closed successfully.
    Stop() error
    // Options returns all agent's options configured via constructor.
    Options() Options

    // Wait waits until agent is stopped  and returns same error as Stop().
    Wait() error
    // After returns a channel that is closed before the agents is stopped.
    // Note: It is not certain the all plugins are stopped, see Error()..
    After() <-chan struct{}
    // Error returns an error that occurret when the agent was stopped.
    // Note: This essentially just calls Stop()..
    Error() error

Agent implements startup & shutdown procedures for plugins.

func NewAgent Uses

func NewAgent(opts ...Option) Agent

NewAgent creates a new agent using given options and registers all flags defined for plugins via config.ForPlugin.

type Option Uses

type Option func(*Options)

Option is a function that operates on an Agent's Option

func AllPlugins Uses

func AllPlugins(plugins ...infra.Plugin) Option

AllPlugins creates an Option that adds all of the nested plugins recursively to the Agent's plugin list.

func Context Uses

func Context(ctx context.Context) Option

Context returns an Option that sets the context for the Agent

func Plugins Uses

func Plugins(plugins ...infra.Plugin) Option

Plugins creates an Option that adds a list of Plugins to the Agent's Plugin list

func QuitOnClose Uses

func QuitOnClose(ch chan struct{}) Option

QuitOnClose returns an Option that will set channel which stops Agent on close

func QuitSignals Uses

func QuitSignals(sigs ...os.Signal) Option

QuitSignals returns an Option that will set signals which stop Agent

func StartTimeout Uses

func StartTimeout(timeout time.Duration) Option

StartTimeout returns an Option that sets timeout for the start of Agent.

func StopTimeout Uses

func StopTimeout(timeout time.Duration) Option

StopTimeout returns an Option that sets timeout for the stop of Agent.

func Version Uses

func Version(buildVer, buildDate, commitHash string) Option

Version returns an Option that sets the version of the Agent to the entered string

type Options Uses

type Options struct {
    StartTimeout time.Duration
    StopTimeout  time.Duration
    QuitSignals  []os.Signal
    QuitChan     chan struct{}
    Context      context.Context
    Plugins      []infra.Plugin
    // contains filtered or unexported fields

Options specifies option list for the Agent

Package agent imports 18 packages (graph) and is imported by 60 packages. Updated 2019-04-29. Refresh now. Tools for package owners.