modules

Documentation

Overview

Package modules contains the base of the module system used in the hotstuff project. The module system allows us to use different implementations of key components, such as the crypto module or the consensus module, and ensures that a module has access to the other modules it depends on.

This package defines a minimal set of modules that are common to both replicas and clients. The consensus package extends this set of modules with many more modules that make up the consensus protocol. If your module does not need access to any of the consensus modules, then you can use this package instead.

There are two main reason one might want to use the module system for a component:

1. To give the component access to other modules.

2. To give other modules access to the component.

To be able to access other modules from a struct, you will need to implement the Module interface from this package. The InitModule method of the Module interface gives your struct a pointer to the Modules object, which can be used to obtain pointers to the other modules. If your module will be interacting with the event loop, then this is the preferred location to set up observers or handlers for events.

To give other modules access to the component, you will need to add a field to the Modules object, add a getter method on the Modules object, and add a check for you module's interface or type in the Builder's Register method. In general you should create an interface for your module if it is possible that someone might want to write their own version of it in the future.

Finally, to set up the module system and its modules, you must create a Builder using the NewBuilder function, and then register all of the modules with the builder using the Register method. For example:

builder := NewBuilder()
// replace the logger
builder.Register(logging.New("foo"))
mods := builder.Build()

If two modules satisfy the same interface, then the one that was registered last will be returned by the module system, though note that both modules will be initialized if they implement the Module interface.

Index

• func GetModule(name string, out interface{}) bool
• func RegisterModule(name string, constructor interface{})
• type Builder
  • func NewBuilder(id hotstuff.ID) Builder
  • func (b *Builder) Build() *Modules
  • func (b *Builder) Register(modules ...interface{})
• type MetricsLogger
  • func NewJSONLogger(wr io.Writer) (MetricsLogger, error)
  • func NopLogger() MetricsLogger
• type Module
• type Modules
  • func (mods Modules) EventLoop() *eventloop.EventLoop
  • func (mods Modules) ID() hotstuff.ID
  • func (mods Modules) Logger() logging.Logger
  • func (mods Modules) MetricsEventLoop() *eventloop.EventLoop
  • func (mods Modules) MetricsLogger() MetricsLogger

Functions

func GetModule

func GetModule(name string, out interface{}) bool

GetModule retrieves a new instance of the module with the specified name. out must be a non-nil pointer to a variable with the interface type of the module. GetModule returns true if the module is found, false otherwise. For example:

var rules consensus.Rules
GetModule("chainedhotstuff", &rules)

func RegisterModule

func RegisterModule(name string, constructor interface{})

RegisterModule registers a module implementation with the specified name. constructor must be a function returning the interface of the module. For example:

RegisterModule("chainedhotstuff", func() consensus.Rules { return chainedhotstuff.New() })

Types

type Builder

type Builder struct {
	// contains filtered or unexported fields
}

Builder is a helper for setting up client modules.

func NewBuilder

func NewBuilder(id hotstuff.ID) Builder

NewBuilder returns a new builder.

func (*Builder) Build

func (b *Builder) Build() *Modules

Build initializes all registered modules and returns the Modules object.

func (*Builder) Register

func (b *Builder) Register(modules ...interface{})

Register registers the modules with the builder.

type MetricsLogger

type MetricsLogger interface {
	Log(proto.Message)
	io.Closer
}

MetricsLogger logs data in protobuf message format.

func NewJSONLogger

func NewJSONLogger(wr io.Writer) (MetricsLogger, error)

NewJSONLogger returns a new metrics logger that logs to the specified writer.

func NopLogger

func NopLogger() MetricsLogger

NopLogger returns a metrics logger that discards any messages. This is useful for testing and other situations where metrics logging is disabled.

type Module

type Module interface {
	// InitModule gives the module access to the other modules.
	InitModule(mods *Modules)
}

Module is an interface for modules that need access to a client.

type Modules

type Modules struct {
	// contains filtered or unexported fields
}

Modules is the base of the module system. It contains only a few core modules that are shared between replicas and clients.

func (Modules) EventLoop

func (mods Modules) EventLoop() *eventloop.EventLoop

EventLoop returns the event loop.

func (Modules) ID

func (mods Modules) ID() hotstuff.ID

ID returns the id of this client.

func (Modules) Logger

func (mods Modules) Logger() logging.Logger

Logger returns the logger.

func (Modules) MetricsEventLoop

func (mods Modules) MetricsEventLoop() *eventloop.EventLoop

MetricsEventLoop returns the metrics event loop. The metrics event loop is used for processing of measurement data.

Deprecated: The metrics event loop is no longer separate from the main event loop. Use EventLoop() instead.

func (Modules) MetricsLogger

func (mods Modules) MetricsLogger() MetricsLogger

MetricsLogger returns the metrics logger.