server

Documentation

Index

• type BalanceTracker
  • func NewBalanceTracker(ns *nodestate.NodeStateMachine, setup BalanceTrackerSetup, ...) *BalanceTracker
  • func (bt *BalanceTracker) GetExpirationTCs() (pos, neg uint64)
  • func (bt *BalanceTracker) GetPosBalanceIDs(start, stop enode.ID, maxCount int) (result []enode.ID)
  • func (bt *BalanceTracker) SetExpirationTCs(pos, neg uint64)
  • func (bt *BalanceTracker) Stop()
  • func (bt *BalanceTracker) TotalTokenAmount() uint64
• type BalanceTrackerSetup
  • func NewBalanceTrackerSetup(setup *nodestate.Setup) BalanceTrackerSetup
  • func (bts *BalanceTrackerSetup) Connect(connAddressField, capacityField nodestate.Field)
• type NodeBalance
  • func (n *NodeBalance) AddBalance(amount int64) (uint64, uint64, error)
  • func (n *NodeBalance) EstMinPriority(at mclock.AbsTime, capacity uint64, update bool) int64
  • func (n *NodeBalance) GetBalance() (uint64, uint64)
  • func (n *NodeBalance) GetPriceFactors() (posFactor, negFactor PriceFactors)
  • func (n *NodeBalance) GetRawBalance() (utils.ExpiredValue, utils.ExpiredValue)
  • func (n *NodeBalance) PosBalanceMissing(targetPriority int64, targetCapacity uint64, after time.Duration) uint64
  • func (n *NodeBalance) Priority(now mclock.AbsTime, capacity uint64) int64
  • func (n *NodeBalance) RequestServed(cost uint64) uint64
  • func (n *NodeBalance) SetBalance(pos, neg uint64) error
  • func (n *NodeBalance) SetPriceFactors(posFactor, negFactor PriceFactors)
• type PriceFactors
• type PriorityPool
  • func NewPriorityPool(ns *nodestate.NodeStateMachine, setup PriorityPoolSetup, clock mclock.Clock, ...) *PriorityPool
  • func (pp *PriorityPool) Active() (uint64, uint64)
  • func (pp *PriorityPool) RequestCapacity(node *enode.Node, targetCap uint64, bias time.Duration, setCap bool) (minPriority int64, allowed bool)
  • func (pp *PriorityPool) SetActiveBias(bias time.Duration)
  • func (pp *PriorityPool) SetLimits(maxCount, maxCap uint64)
• type PriorityPoolSetup
  • func NewPriorityPoolSetup(setup *nodestate.Setup) PriorityPoolSetup
  • func (pps *PriorityPoolSetup) Connect(priorityField nodestate.Field, updateFlag nodestate.Flags)

Types

type BalanceTracker

type BalanceTracker struct {
	BalanceTrackerSetup
	// contains filtered or unexported fields
}

BalanceTracker tracks positive and negative balances for connected nodes. After connAddressField is set externally, a NodeBalance is created and previous balance values are loaded from the database. Both balances are exponentially expired values. Costs are deducted from the positive balance if present, otherwise added to the negative balance. If the capacity is non-zero then a time cost is applied continuously while individual request costs are applied immediately. The two balances are translated into a single priority value that also depends on the actual capacity.

func NewBalanceTracker

func NewBalanceTracker(ns *nodestate.NodeStateMachine, setup BalanceTrackerSetup, db ethdb.KeyValueStore, clock mclock.Clock, posExp, negExp utils.ValueExpirer) *BalanceTracker

NewBalanceTracker creates a new BalanceTracker

func (*BalanceTracker) GetExpirationTCs

func (bt *BalanceTracker) GetExpirationTCs() (pos, neg uint64)

GetExpirationTCs returns the current positive and negative token expiration time constants

func (*BalanceTracker) GetPosBalanceIDs

func (bt *BalanceTracker) GetPosBalanceIDs(start, stop enode.ID, maxCount int) (result []enode.ID)

GetPosBalanceIDs lists node IDs with an associated positive balance

func (*BalanceTracker) SetExpirationTCs

func (bt *BalanceTracker) SetExpirationTCs(pos, neg uint64)

SetExpirationTCs sets positive and negative token expiration time constants. Specified in seconds, 0 means infinite (no expiration).

func (*BalanceTracker) Stop

func (bt *BalanceTracker) Stop()

Stop saves expiration offset and unsaved node balances and shuts BalanceTracker down

func (*BalanceTracker) TotalTokenAmount

func (bt *BalanceTracker) TotalTokenAmount() uint64

TotalTokenAmount returns the current total amount of service tokens in existence

type BalanceTrackerSetup

type BalanceTrackerSetup struct {
	// controlled by PriorityPool
	PriorityFlag, UpdateFlag nodestate.Flags
	BalanceField             nodestate.Field
	// contains filtered or unexported fields
}

BalanceTrackerSetup contains node state flags and fields used by BalanceTracker

func NewBalanceTrackerSetup

func NewBalanceTrackerSetup(setup *nodestate.Setup) BalanceTrackerSetup

NewBalanceTrackerSetup creates a new BalanceTrackerSetup and initializes the fields and flags controlled by BalanceTracker

func (*BalanceTrackerSetup) Connect

func (bts *BalanceTrackerSetup) Connect(connAddressField, capacityField nodestate.Field)

Connect sets the fields used by BalanceTracker as an input

type NodeBalance

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

NodeBalance keeps track of the positive and negative balances of a connected client and calculates actual and projected future priority values. Implements nodePriority interface.

func (*NodeBalance) AddBalance

func (n *NodeBalance) AddBalance(amount int64) (uint64, uint64, error)

AddBalance adds the given amount to the positive balance and returns the balance before and after the operation. Exceeding maxBalance results in an error (balance is unchanged) while adding a negative amount higher than the current balance results in zero balance.

func (*NodeBalance) EstMinPriority

func (n *NodeBalance) EstMinPriority(at mclock.AbsTime, capacity uint64, update bool) int64

EstMinPriority gives a lower estimate for the priority at a given time in the future. An average request cost per time is assumed that is twice the average cost per time in the current session. If update is true then a priority callback is added that turns UpdateFlag on and off in case the priority goes below the estimated minimum.

func (*NodeBalance) GetBalance

func (n *NodeBalance) GetBalance() (uint64, uint64)

GetBalance returns the current positive and negative balance.

func (*NodeBalance) GetPriceFactors

func (n *NodeBalance) GetPriceFactors() (posFactor, negFactor PriceFactors)

GetPriceFactors returns the price factors

func (*NodeBalance) GetRawBalance

func (n *NodeBalance) GetRawBalance() (utils.ExpiredValue, utils.ExpiredValue)

GetRawBalance returns the current positive and negative balance but in the raw(expired value) format.

func (*NodeBalance) PosBalanceMissing

func (n *NodeBalance) PosBalanceMissing(targetPriority int64, targetCapacity uint64, after time.Duration) uint64

PosBalanceMissing calculates the missing amount of positive balance in order to connect at targetCapacity, stay connected for the given amount of time and then still have a priority of targetPriority

func (*NodeBalance) Priority

func (n *NodeBalance) Priority(now mclock.AbsTime, capacity uint64) int64

Priority returns the actual priority based on the current balance

func (*NodeBalance) RequestServed

func (n *NodeBalance) RequestServed(cost uint64) uint64

RequestServed should be called after serving a request for the given peer

func (*NodeBalance) SetBalance

func (n *NodeBalance) SetBalance(pos, neg uint64) error

SetBalance sets the positive and negative balance to the given values

func (*NodeBalance) SetPriceFactors

func (n *NodeBalance) SetPriceFactors(posFactor, negFactor PriceFactors)

SetPriceFactors sets the price factors. TimeFactor is the price of a nanosecond of connection while RequestFactor is the price of a request cost unit.

type PriceFactors

type PriceFactors struct {
	TimeFactor, CapacityFactor, RequestFactor float64
}

PriceFactors determine the pricing policy (may apply either to positive or negative balances which may have different factors). - TimeFactor is cost unit per nanosecond of connection time - CapacityFactor is cost unit per nanosecond of connection time per 1000000 capacity - RequestFactor is cost unit per request "realCost" unit

type PriorityPool

type PriorityPool struct {
	PriorityPoolSetup
	// contains filtered or unexported fields
}

PriorityPool handles a set of nodes where each node has a capacity (a scalar value) and a priority (which can change over time and can also depend on the capacity). A node is active if it has at least the necessary minimal amount of capacity while inactive nodes have 0 capacity (values between 0 and the minimum are not allowed). The pool ensures that the number and total capacity of all active nodes are limited and the highest priority nodes are active at all times (limits can be changed during operation with immediate effect).

When activating clients a priority bias is applied in favor of the already active nodes in order to avoid nodes quickly alternating between active and inactive states when their priorities are close to each other. The bias is specified in terms of duration (time) because priorities are expected to usually get lower over time and therefore a future minimum prediction (see EstMinPriority) should monotonously decrease with the specified time parameter. This time bias can be interpreted as minimum expected active time at the given capacity (if the threshold priority stays the same).

Nodes in the pool always have either InactiveFlag or ActiveFlag set. A new node is added to the pool by externally setting InactiveFlag. PriorityPool can switch a node between InactiveFlag and ActiveFlag at any time. Nodes can be removed from the pool by externally resetting both flags. ActiveFlag should not be set externally.

The highest priority nodes in "inactive" state are moved to "active" state as soon as the minimum capacity can be granted for them. The capacity of lower priority active nodes is reduced or they are demoted to "inactive" state if their priority is insufficient even at minimal capacity.

func NewPriorityPool

func NewPriorityPool(ns *nodestate.NodeStateMachine, setup PriorityPoolSetup, clock mclock.Clock, minCap uint64, activeBias time.Duration, capacityStepDiv uint64) *PriorityPool

NewPriorityPool creates a new PriorityPool

func (*PriorityPool) Active

func (pp *PriorityPool) Active() (uint64, uint64)

Active returns the number and total capacity of currently active nodes

func (*PriorityPool) RequestCapacity

func (pp *PriorityPool) RequestCapacity(node *enode.Node, targetCap uint64, bias time.Duration, setCap bool) (minPriority int64, allowed bool)

RequestCapacity checks whether changing the capacity of a node to the given target is possible (bias is applied in favor of other active nodes if the target is higher than the current capacity). If setCap is true then it also performs the change if possible. The function returns the minimum priority needed to do the change and whether it is currently allowed. If setCap and allowed are both true then the caller can assume that the change was successful. Note: priorityField should always be set before calling RequestCapacity. If setCap is false then both InactiveFlag and ActiveFlag can be unset and they are not changed by this function call either. Note 2: this function should run inside a NodeStateMachine operation

func (*PriorityPool) SetActiveBias

func (pp *PriorityPool) SetActiveBias(bias time.Duration)

SetActiveBias sets the bias applied when trying to activate inactive nodes

func (*PriorityPool) SetLimits

func (pp *PriorityPool) SetLimits(maxCount, maxCap uint64)

SetLimits sets the maximum number and total capacity of simultaneously active nodes

type PriorityPoolSetup

type PriorityPoolSetup struct {
	// controlled by PriorityPool
	ActiveFlag, InactiveFlag nodestate.Flags
	CapacityField            nodestate.Field
	// contains filtered or unexported fields
}

PriorityPoolSetup contains node state flags and fields used by PriorityPool Note: ActiveFlag and InactiveFlag can be controlled both externally and by the pool, see PriorityPool description for details.

func NewPriorityPoolSetup

func NewPriorityPoolSetup(setup *nodestate.Setup) PriorityPoolSetup

NewPriorityPoolSetup creates a new PriorityPoolSetup and initializes the fields and flags controlled by PriorityPool

func (*PriorityPoolSetup) Connect

func (pps *PriorityPoolSetup) Connect(priorityField nodestate.Field, updateFlag nodestate.Flags)

Connect sets the fields and flags used by PriorityPool as an input