Documentation ¶
Index ¶
- Variables
- type Field
- type FieldCallback
- type 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 (ns *NodeStateMachine) AddLogMetrics(requireFlags, disableFlags Flags, name string, inMeter, outMeter metrics.Meter, ...)
- func (ns *NodeStateMachine) AddTimeout(n *enode.Node, flags Flags, timeout time.Duration) error
- 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) GetState(n *enode.Node) Flags
- func (ns *NodeStateMachine) Operation(fn func()) error
- func (ns *NodeStateMachine) Persist(n *enode.Node) error
- func (ns *NodeStateMachine) SetField(n *enode.Node, field Field, value interface{}) error
- func (ns *NodeStateMachine) SetFieldSub(n *enode.Node, field Field, value interface{}) error
- func (ns *NodeStateMachine) SetState(n *enode.Node, setFlags, resetFlags Flags, timeout time.Duration) error
- func (ns *NodeStateMachine) SetStateSub(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
Constants ¶
This section is empty.
Variables ¶
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 ¶
FieldCallback is a subscription callback which is called when the value of a specific field is changed. 字段发生变化时的回调函数 state表示字段发生变化时的状态,字段从oldValue变成了newValue
type Flags ¶
type Flags struct {
// contains filtered or unexported fields
}
Flags represents a set of flags from a certain setup
func MergeFlags ¶
MergeFlags merges multiple sets of state flags 将所有输入的Flags的mask进行或运算,得到最终结果
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 当有节点进入或退出指定的范围的时候进行记录 指定的范围指requireFlags中为1的全为1,disableFlags为1的全为0 inMeter统计节点进入范围的次数,outMeter统计节点退出范围的次数,gauge记录进出范围的总次数
func (*NodeStateMachine) AddTimeout ¶
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. 针对所有符合要求的节点调用回调函数 也就是requireFlags中为1全为1,disableFlags中为1的全为0
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 找到指定ID的节点
func (*NodeStateMachine) GetState ¶
func (ns *NodeStateMachine) GetState(n *enode.Node) Flags
GetState retrieves the current state 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) 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). 这个函数用于SubscribeState,SubscribeField或者Operation的回调函数中调用
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. 将setFlags中位修改为1,resetFlags中的位修改为0 如果指定了timeout,那么超时后setFlags中的位会被重置为0
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). 这个函数用于SubscribeState,SubscribeField或者Operation的回调函数中调用
func (*NodeStateMachine) Start ¶
func (ns *NodeStateMachine) Start()
Start starts the state machine, enabling state and field operations and disabling further subscriptions. 启动状态机,执行Start后不再允许订阅状态或者字段
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. 该函数必须在Start函数之前调用 将回调函数记录到指定的field下 也就是ns.fields[index].subs中增加一项,index是这个field所在的下标,保存在Field对象中
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. 该函数必须在Start函数之前调用 输入的Flags中比特位为1的位置是被订阅的位置,当这些位置发生变动的时候会调用回调函数
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 ¶
NewField creates a new node state field 在Setup.fields中新增一个fieldDefinition对象,其中encode和decode为nil
func (*Setup) NewFlag ¶
NewFlag creates a new node state flag 在Setup.flags中新增一个flagDefinition对象,其中persistent为false 返回的Flags中有一位是1,具体位置取决于Setup之前已经有多少个flags
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 在Setup.fields中新增一个fieldDefinition对象,参数中指定了其中的encode和decode
func (*Setup) NewPersistentFlag ¶
NewPersistentFlag creates a new persistent node state flag 在Setup.flags中新增一个flagDefinition对象,其中persistent为true 返回的Flags中有一位是1,具体位置取决于Setup之前已经有多少个flags
func (*Setup) OfflineFlag ¶
OfflineFlag returns the system-defined offline flag belonging to the given setup 获得offline的Flags对象 它的mask就是1,相当于左移0位,因为offline保存在Setup.flags的最开始位置
type StateCallback ¶
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. 状态发生变化时的回调函数 oldState和newState中只有被订阅的那些比特位有意义 代表此时发生了从oldState到newState的状态变化