README
¶
Linker
Linker is Dependency Injection and Inversion of Control package. It supports the following features:
- Components registry
- Automatic dependency injection of the registered components
- Components lifecycle support via
PostConstructor,InitializerandShutdownerinterfaces implementations - Post-injection notification
- Automatic ordering of components initialization
- Circular dependency detection
- Components shutdowning
Please refer to this blogpost for some details.
Linker is used by Logrange, please take a look how it is used there.
import (
"github.com/logrange/linker"
)
type DatabaseAccessService interface {
RunQuery(query string) DbResult
}
// MySQLAccessService implements DatabaseAccessService
type MySQLAccessService struct {
// Conns uses field's tag to specify injection param name(mySqlConns)
// or sets-up the default value(32), if the param is not provided
Conns int `inject:"mySqlConns, optional:32"`
}
type BigDataService struct {
// DBa has DatabaseAccessService type which value will be injected by the injector
// in its Init() function, or it fails if there is no appropriate component with the name(dba)
// was registered...
DBa DatabaseAccessService `inject:"dba"`
}
...
func main() {
// 1st step is to create the injector
inj := linker.New()
// 2nd step is to register components
inj.Register(
linker.Component{Name: "dba", Value: &MySQLAccessService{}},
linker.Component{Name: "", Value: &BigDataService{}},
linker.Component{Name: "mySqlConns", Value: int(msconns)},
...
)
// 3rd step is to inject dependecies and initialize the registered components
inj.Init(ctx)
// the injector fails-fast, so if no panic everything is good so far.
...
// 4th de-initialize all compoments properly
inj.Shutdown()
}
Annotate fields using fields tags
The inject tag field has the following format:
inject: "<name>[,optional[:<defaultValue]]"
So annotated fields can be assigned using different rules:
// Field will be assigned by component with registration name "compName",
// if there is no comonent with the name, or it could not be assigned to the type
// FieldType, panic will happen
Field FieldType `inject:"compName"`
// Field will be assigned by component with any name (indicated as ""), which could be
// assigned to the FieldType. If no such component or many matches to the type,
// panic will happen.
Field FieldType `inject:""`
// If no components match to either Field1 or Field2 they will be skipped with
// no panic. Ambigious situation still panics
Field1 FieldType `inject:"aaa, optional"`
Field2 FieldType `inject:", optional"`
// Default values could be provided for numeric and string types. The
// default values will be assigned if no components match to the rules
NumFld int `inject:"intFld, optional: 21"`
StrFld string `inject:"strFld,optional:abc"`
Create the injector
Injector is a main object, which controls the components: registers them, initializes, checks and provides initialization and shutdown calls.
inj := linker.New()
Register components using names or anonymously
Component is an object that can be used for initialization of other components, or which requires an initialization. Components can have different types, but only fields of components, with 'pointer to struct' type, could be assigned by the Injector. Injector is responsible for the injection(initialization a component's fields) process. All components must be registered in injector via Register() function before the initialization process will be run.
Initialize components
When all components are registered Init() function of the Injector allows to perform initialization. The Init() function does the following actions:
- Walks over all registered components and assigns all tagged fields using named and unnamed components. If no matches or ambiguity happens, the
Init()can panic. - For components, which implement linker.PostConstructor interface, the
PostConstruct()function will be called. - For components, which implements linker.Initializer interface, the
Init(ctx)function will be called in a specific order. The initialization order is defined as following: less dependent components are initialized before the components - If circular dependency between registered components is found, Init() will panic.
Shutting down registered components properly
Properly initialized components could be shut-down in back-initialization order by calling Shutdown() function of the injector. Components, that implement linker.Shutdowner interface, will be called by the Shutdown()
Documentation
¶
Overview ¶
Package linker provides Dependency Injection and Inversion of Control functionality. The core component is Injector, which allows to register Components. Component is an object, which can have any type, which requires some initialization, or can be used for initializing other components. Every component is registered in the Injector by the component name or anonymously (empty name). Same object can be registered by different names. This could be useful if the object implements different interfaces that can be used by different components.
The package contains several interfaces: PostConstructor, Initializer and Shutdowner, which could be implemented by components with a purpose to be called by Injector on different initialization/de-initialization phases.
Init() function of Injector allows to initialize registered components. The initialization process supposes that components with 'pointer to struct' type or interfaces, which contains a 'pointer to struct' will be initialized. The initialization supposes to inject (assign) the struct fields values using other registered components. Injector matches them by name or by type. Injector uses fail-fast strategy so any error is considered like misconfiguraion and a panic happens.
When all components are initialized, the components, which implement PostConstructor interface will be notified via PostConsturct() function call. The order of PostConstruct() calls is not defined.
After the construction phase, injector builds dependencies graph with a purpose to detect dependency loops and to establish components initialization order. If a dependency loop is found, Injector will panic. Components, which implement Initializer interface, will be notified in specific order by Init(ctx) function call. Less dependant components will be initialized before the components that have dependency on the first ones.
Injector is supposed to be called from one go-routine and doesn't support calls from multiple go-routines.
Initialization process could take significant time, so context is provided. If the context is cancelled or closed it will be detected either by appropriate component or by the Injector what will cause of de-intializing already initialized components using Shutdown() function call (if provided) in reverse of the initialization order. Panic will happen then.
Index ¶
Constants ¶
const (
// DefaultTagName contains the tag name, used by the Injector by default
DefaultTagName = "inject"
)
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Component ¶
type Component struct {
// Name contains the component name
Name string
// Value contains the component which is registered in the Injector
Value interface{}
}
Component struct wraps a component, which is placed into Value field. The struct is used for registering components in Injector.
type Initializer ¶
type Initializer interface {
// Init will be called by Injector in a specific order after all components
// are constructed. The order of calling the Init() functions is defined
// by the dependency injection graph. Init() function of a component will
// be called after initializing all dependencies of the component.
//
// If the initialization of the component is failed a non-nil result
// must be returned. This case Injector will shutdown
// all previously initialized components and fail the initialization phase
// returning an error in its Init() calle.
//
// if the Init() is ever called, it always happens before Shutdown().
Init(ctx context.Context) error
}
Initializer interface provides a component initialization functionality. A component can implement the interface to provide Init() function where the component can acquire resources and perform some initialization.
type Injector ¶
type Injector struct {
// contains filtered or unexported fields
}
Injector struct keeps the list of a program components and controls their life-cycle. Injector's life-cycle consists of the following phases, which are executed sequentually:
1. Registration phase. Components are added to the injector, or registered there via Register() function.
2. Construct phase. In the phase, the Injector walks over fields of every registered component and it adds appropriate dependency found in between other components. The phase is started by Init() call.
3. Initialization phase. On the phase the Injector builds components dependencies graph and initialize each component in an order. Dependant components must be initialize after their dependencies. This phase is done in context of Init() call.
4. Shutdown phase. On the phase components are de-initialied or being shutdowned. Components are shutdowned in a reverse of their initialization order. The phase is performed by Shutdown() call
Injector doesn't allow to have cycles in the component dependency graph. A dependency cycle is a situation when component A has dependency from a component B, which has directly, or indirectly (through another direct dependency) a dependency from the component A.
The implementation is not concurrent and must be used within one go-routine or be synchronized properly. Normal flow is as the following:
Register() Init() Shutdown()
The Injector uses fail-fast strategy and it panics if any error happens. Shutdown must not be called if Init() was panicing or not called at all.
func (*Injector) Init ¶
Init initializes components. It does the following things in a row: 1. Inject all dependencies 2. it calls PostConsturct() functions for PostConstructors 3. it builds an initialization order and calls Init() for Initializors
If any error happens, it panics. If an error happens on initialization phase, it's shutting down already initialized components, then panics. If the method is over with no panic, Shutdown() must be called to free all resources properly
func (*Injector) Register ¶
Register called to register programming components. It must be called before Init().
type Logger ¶
type Logger interface {
// Info prints an information message into the log
Info(args ...interface{})
// Debug prints a debug message into the log
Debug(args ...interface{})
}
Logger interface is used by Injector to print its logs
type PostConstructor ¶
type PostConstructor interface {
// PostConstruct is called by Injector in the end of construct phase.
// If a component implements the interface, the PostConstruct() will be
// called immediately after all dependencies are resolved and injected.
// PostConstruct is always called before Init() (see Initializer) and
// Shutdown() (see Shutdowner) if they are implemented
//
// PostConstruct is supposed to be quick and should not block the calling
// go-routine. If some initialization or blocking could happen, it must
// be done in Init() method
PostConstruct()
}
PostConstructor interface. Components can implement it to provide a post- construct action (see PostConstruct).
type Shutdowner ¶
type Shutdowner interface {
// Shutdown allows to shutdown a component. Injector calls the function
// on shutdown phase. It never calls Shutdown() for the components, that
// were not initialized successfully (Init() was not called, or it returned
// an error)
Shutdown()
}
Shutdowner interface allows to provide Shutdown() function which will be called by Injector to shutdown the component properly. A component can implement the interface to release all resources, acquired on initialization phase.
Source Files