nodestate

Documentation

Index

• type Field
• type FieldCallback
• type Flags
  • func MergeFlags(list ...Flags) Flags
  • func (a Flags) And(b Flags) Flags
  • func (a Flags) AndNot(b Flags) Flags
  • func (a Flags) Equals(b Flags) bool
  • func (a Flags) HasAll(b Flags) bool
  • func (a Flags) HasNone(b Flags) bool
  • func (a Flags) IsEmpty() bool
  • func (a Flags) Or(b Flags) Flags
  • func (f Flags) String() string
  • func (a Flags) Xor(b Flags) Flags
• type NodeStateMachine
  • func NewNodeStateMachine(db ethdb.KeyValueStore, dbKey []byte, clock mclock.Clock, setup *Setup) *NodeStateMachine
  • func (ns *NodeStateMachine) AddLogMetrics(requireFlags, disableFlags Flags, name string, inMeter, outMeter metrics.Meter, ...)
  • func (ns *NodeStateMachine) AddTimeout(n *enode.Node, flags Flags, timeout time.Duration)
  • func (ns *NodeStateMachine) ForEach(requireFlags, disableFlags Flags, cb func(n *enode.Node, state Flags))
  • func (ns *NodeStateMachine) GetField(n *enode.Node, field Field) interface{}
  • func (ns *NodeStateMachine) GetNode(id enode.ID) *enode.Node
  • func (ns *NodeStateMachine) Persist(n *enode.Node) error
  • func (ns *NodeStateMachine) SetField(n *enode.Node, field Field, value interface{}) error
  • func (ns *NodeStateMachine) SetState(n *enode.Node, setFlags, resetFlags Flags, timeout time.Duration)
  • func (ns *NodeStateMachine) Start()
  • func (ns *NodeStateMachine) Stop()
  • func (ns *NodeStateMachine) SubscribeField(field Field, callback FieldCallback)
  • func (ns *NodeStateMachine) SubscribeState(flags Flags, callback StateCallback)
• type Setup
  • func (s *Setup) NewField(name string, ftype reflect.Type) Field
  • func (s *Setup) NewFlag(name string) Flags
  • func (s *Setup) NewPersistentField(name string, ftype reflect.Type, encode func(interface{}) ([]byte, error), ...) Field
  • func (s *Setup) NewPersistentFlag(name string) Flags
  • func (s *Setup) OfflineFlag() Flags
• type StateCallback

Types

type Field

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

Field represents a field from a certain setup

type FieldCallback

type FieldCallback func(n *enode.Node, state Flags, oldValue, newValue interface{})

FieldCallback is a subscription callback which is called when the value of a specific field is changed.

type Flags

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

Flags represents a set of flags from a certain setup

func MergeFlags

func MergeFlags(list ...Flags) Flags

MergeFlags merges multiple sets of state flags

func (Flags) And

func (a Flags) And(b Flags) Flags

And returns the set of flags present in both a and b

func (Flags) AndNot

func (a Flags) AndNot(b Flags) Flags

AndNot returns the set of flags present in a but not in b

func (Flags) Equals

func (a Flags) Equals(b Flags) bool

Equals returns true if a and b have the same flags set

func (Flags) HasAll

func (a Flags) HasAll(b Flags) bool

HasAll returns true if b is a subset of a

func (Flags) HasNone

func (a Flags) HasNone(b Flags) bool

HasNone returns true if a and b have no shared flags

func (Flags) IsEmpty

func (a Flags) IsEmpty() bool

IsEmpty returns true if a has no flags set

func (Flags) Or

func (a Flags) Or(b Flags) Flags

Or returns the set of flags present in either a or b

func (Flags) String

func (f Flags) String() string

String returns a list of the names of the flags specified in the bit mask

func (Flags) Xor

func (a Flags) Xor(b Flags) Flags

Xor returns the set of flags present in either a or b but not both

type NodeStateMachine

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

NodeStateMachine connects different system components operating on subsets of network nodes. Node states are represented by 64 bit vectors with each bit assigned to a state flag. Each state flag has a descriptor structure and the mapping is created automatically. It is possible to subscribe to subsets of state flags and receive a callback if one of the nodes has a relevant state flag changed. Callbacks can also modify further flags of the same node or other nodes. State updates only return after all immediate effects throughout the system have happened (deadlocks should be avoided by design of the implemented state logic). The caller can also add timeouts assigned to a certain node and a subset of state flags. If the timeout elapses, the flags are reset. If all relevant flags are reset then the timer is dropped. State flags with no timeout are persisted in the database if the flag descriptor enables saving. If a node has no state flags set at any moment then it is discarded.

Extra node fields can also be registered so system components can also store more complex state for each node that is relevant to them, without creating a custom peer set. Fields can be shared across multiple components if they all know the field ID. Subscription to fields is also possible. Persistent fields should have an encoder and a decoder function.

func NewNodeStateMachine

func NewNodeStateMachine(db ethdb.KeyValueStore, dbKey []byte, clock mclock.Clock, setup *Setup) *NodeStateMachine

NewNodeStateMachine creates a new node state machine. If db is not nil then the node states, fields and active timeouts are persisted. Persistence can be enabled or disabled for each state flag and field.

func (*NodeStateMachine) AddLogMetrics

func (ns *NodeStateMachine) AddLogMetrics(requireFlags, disableFlags Flags, name string, inMeter, outMeter metrics.Meter, gauge metrics.Gauge)

AddLogMetrics adds logging and/or metrics for nodes entering, exiting and currently being in a given set specified by required and disabled state flags

func (*NodeStateMachine) AddTimeout

func (ns *NodeStateMachine) AddTimeout(n *enode.Node, flags Flags, timeout time.Duration)

AddTimeout adds a node state timeout associated to the given state flag(s). After the specified time interval, the relevant states will be reset.

func (*NodeStateMachine) ForEach

func (ns *NodeStateMachine) ForEach(requireFlags, disableFlags Flags, cb func(n *enode.Node, state Flags))

ForEach calls the callback for each node having all of the required and none of the disabled flags set

func (*NodeStateMachine) GetField

func (ns *NodeStateMachine) GetField(n *enode.Node, field Field) interface{}

GetField retrieves the given field of the given node

func (*NodeStateMachine) GetNode

func (ns *NodeStateMachine) GetNode(id enode.ID) *enode.Node

GetNode returns the enode currently associated with the given ID

func (*NodeStateMachine) Persist

func (ns *NodeStateMachine) Persist(n *enode.Node) error

Persist saves the persistent state and fields of the given node immediately

func (*NodeStateMachine) SetField

func (ns *NodeStateMachine) SetField(n *enode.Node, field Field, value interface{}) error

SetField sets the given field of the given node

func (*NodeStateMachine) SetState

func (ns *NodeStateMachine) SetState(n *enode.Node, setFlags, resetFlags Flags, timeout time.Duration)

SetState updates the given node state flags and processes all resulting callbacks. It only returns after all subsequent immediate changes (including those changed by the callbacks) have been processed. If a flag with a timeout is set again, the operation removes or replaces the existing timeout.

func (*NodeStateMachine) Start

func (ns *NodeStateMachine) Start()

Start starts the state machine, enabling state and field operations and disabling further subscriptions.

func (*NodeStateMachine) Stop

func (ns *NodeStateMachine) Stop()

Stop stops the state machine and saves its state if a database was supplied

func (*NodeStateMachine) SubscribeField

func (ns *NodeStateMachine) SubscribeField(field Field, callback FieldCallback)

SubscribeField adds a node field subscription. Same rules apply as for SubscribeState.

func (*NodeStateMachine) SubscribeState

func (ns *NodeStateMachine) SubscribeState(flags Flags, callback StateCallback)

SubscribeState adds a node state subscription. The callback is called while the state machine mutex is not held and it is allowed to make further state updates. All immediate changes throughout the system are processed in the same thread/goroutine. It is the responsibility of the implemented state logic to avoid deadlocks caused by the callbacks, infinite toggling of flags or hazardous/non-deterministic state changes. State subscriptions should be installed before loading the node database or making the first state update.

type Setup

type Setup struct {
	Version uint
	// contains filtered or unexported fields
}

stateSetup contains the list of flags and fields used by the application

func (*Setup) NewField

func (s *Setup) NewField(name string, ftype reflect.Type) Field

NewField creates a new node state field

func (*Setup) NewFlag

func (s *Setup) NewFlag(name string) Flags

NewFlag creates a new node state flag

func (*Setup) NewPersistentField

func (s *Setup) NewPersistentField(name string, ftype reflect.Type, encode func(interface{}) ([]byte, error), decode func([]byte) (interface{}, error)) Field

NewPersistentField creates a new persistent node field

func (*Setup) NewPersistentFlag

func (s *Setup) NewPersistentFlag(name string) Flags

NewPersistentFlag creates a new persistent node state flag

func (*Setup) OfflineFlag

func (s *Setup) OfflineFlag() Flags

OfflineFlag returns the system-defined offline flag belonging to the given setup

type StateCallback

type StateCallback func(n *enode.Node, oldState, newState Flags)

StateCallback is a subscription callback which is called when one of the state flags that is included in the subscription state mask is changed. Note: oldState and newState are also masked with the subscription mask so only the relevant bits are included.