Documentation

Index

Constants

This section is empty.

Variables

View Source
var (
	ErrInvalidField = errors.New("invalid field type")
	ErrClosed       = errors.New("already closed")
)

Functions

This section is empty.

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 implements a network node-related event subscription system. It can assign binary state flags and fields of arbitrary type to each node and allows subscriptions to flag/field changes which can also modify further flags and fields, potentially triggering further subscriptions. An operation includes an initial change and all resulting subsequent changes and always ends in a consistent global state. It is initiated by a "top level" SetState/SetField call that blocks (also blocking other top-level functions) until the operation is finished. Callbacks making further changes should use the non-blocking SetStateSub/SetFieldSub functions. The tree of events resulting from the initial changes is traversed in a breadth-first order, ensuring for each subscription callback that all other callbacks caused by the same change triggering the current callback are processed before anything is triggered by the changes made in the current callback. In practice this logic ensures that all subscriptions "see" events in the logical order, callbacks are never called concurrently and "back and forth" effects are also possible. The state machine design should ensure that infinite event cycles cannot happen. 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. Note: in order to avoid mutex deadlocks the callbacks should never lock a mutex that might be locked when the top level SetState/SetField functions are called. If a function potentially performs state/field changes then it is recommended to mention this fact in the function description, along with whether it should run inside an operation callback.

                              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) error

                                    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. Note that this callback is not an operation callback but ForEach can be called from an Operation callback or Operation can also be called from a ForEach callback if necessary.

                                      func (*NodeStateMachine) GetField

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

                                        GetField retrieves the given field of the given node. Note that when used in a subscription callback the result can be out of sync with the state change represented by the callback parameters so extra safety checks might be necessary.

                                        func (*NodeStateMachine) GetNode

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

                                          GetNode returns the enode currently associated with the given ID

                                          func (*NodeStateMachine) Operation

                                          func (ns *NodeStateMachine) Operation(fn func()) error

                                            Operation calls the given function as an operation callback. This allows the caller to start an operation with multiple initial changes. The same rules apply as for subscription callbacks.

                                            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 and blocks until the operation is finished

                                                func (*NodeStateMachine) SetFieldSub

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

                                                  SetFieldSub sets the given field of the given node without blocking (should be called from a subscription/operation callback).

                                                  func (*NodeStateMachine) SetState

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

                                                    SetState updates the given node state flags and blocks until the operation is finished. If a flag with a timeout is set again, the operation removes or replaces the existing timeout.

                                                    func (*NodeStateMachine) SetStateSub

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

                                                      SetStateSub updates the given node state flags without blocking (should be called from a subscription/operation callback).

                                                      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 using the non-blocking SetStateSub/SetFieldSub functions. All callbacks of an operation are running from the thread/goroutine of the initial caller and parallel operations are not permitted. Therefore the callback is never called concurrently. It is the responsibility of the implemented state logic to avoid deadlocks and to reach a stable state in a finite amount of steps. 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.

                                                                            Source Files