ouroboros-network-0.1.0.0: A networking layer for the Ouroboros blockchain protocol
Safe HaskellNone
LanguageHaskell2010

Ouroboros.Network.PeerSelection.Governor.Types

Synopsis

P2P governor policies

data PeerSelectionTargets Source #

Adjustable targets for the peer selection mechanism.

These are used by the peer selection governor as targets. They are used by the peer churn governor loop as knobs to adjust, to influence the peer selection governor.

The known, established and active peer targets are targets both from below and from above: the governor will attempt to grow or shrink the sets to hit these targets.

Unlike the other targets, the root peer target is "one sided", it is only a target from below. The governor does not try to shrink the root set to hit it, it simply stops looking for more.

There is also an implicit target that enough local root peers are selected as active. This comes from the configuration for local roots, and is not an independently adjustable target.

type PickPolicy peeraddr m = (peeraddr → PeerSource) → (peeraddr → Int) → (peeraddr → Bool) → Set peeraddr → Int → STM m (Set peeraddr) Source #

A peer pick policy is an action that picks a subset of elements from a map of peers.

The pre-condition is that the map of available choices will be non-empty, and the requested number to pick will be strictly positive.

The post-condition is that the picked set is non-empty but must not be bigger than the requested number.

pickPeers ∷ (Ord peeraddr, Functor m) ⇒ PeerSelectionState peeraddr peerconn → ((peeraddr → PeerSource) → (peeraddr → Int) → (peeraddr → Bool) → Set peeraddr → Int → m (Set peeraddr)) → Set peeraddr → Int → m (Set peeraddr) Source #

Check pre-conditions and post-conditions on the pick policies, and supply additional peer atributes from the current state.

P2P governor low level API

data PeerStateActions peeraddr peerconn m Source #

Callbacks which are performed to change peer state.

Constructors

PeerStateActions 

Fields

data PeerSelectionActions peeraddr peerconn m Source #

Actions performed by the peer selection governor.

These being pluggable allows:

  • choice of known peer root sets
  • running both in simulation and for real

Constructors

PeerSelectionActions 

Fields

  • readPeerSelectionTargets ∷ STM m PeerSelectionTargets
     
  • readLocalRootPeers ∷ STM m [(Int, Map peeraddr PeerAdvertise)]

    Read the current set of locally or privately known root peers.

    In general this is expected to be updated asynchronously by some other thread. It is intended to cover the use case of peers from local configuration. It could be dynamic due to DNS resolution, or due to dynamic configuration updates.

    It is structured as a collection of (non-overlapping) groups of peers where we are supposed to select n from each group.

  • requestPublicRootPeersInt → m (Set peeraddr, DiffTime)

    Request a sample of public root peers.

    It is intended to cover use cases including:

    • federated relays from a DNS pool
    • stake pool relays published in the blockchain
    • a pre-distributed snapshot of stake pool relays from the blockchain
  • requestPeerGossip ∷ peeraddr → m [peeraddr]

    The action to contact a known peer and request a sample of its known peers.

    This is synchronous, but it should expect to be interrupted by a timeout asynchronous exception. Failures are throw as exceptions.

  • peerStateActionsPeerStateActions peeraddr peerconn m

    Core actions run by the governor to change PeerStatus.

P2P govnernor internals

data PeerSelectionState peeraddr peerconn Source #

The internal state used by the peerSelectionGovernor.

The local and public root sets are disjoint, and their union is the overall root set.

Constructors

PeerSelectionState 

Fields

Instances

Instances details
Functor (PeerSelectionState peeraddr) Source # 
Instance details

Defined in Ouroboros.Network.PeerSelection.Governor.Types

Methods

fmap ∷ (a → b) → PeerSelectionState peeraddr a → PeerSelectionState peeraddr b Source #

(<$) ∷ a → PeerSelectionState peeraddr b → PeerSelectionState peeraddr a Source #

(Ord peeraddr, Show peeraddr, Show peerconn) ⇒ Show (PeerSelectionState peeraddr peerconn) Source # 
Instance details

Defined in Ouroboros.Network.PeerSelection.Governor.Types

Methods

showsPrecIntPeerSelectionState peeraddr peerconn → ShowS Source #

showPeerSelectionState peeraddr peerconn → String Source #

showList ∷ [PeerSelectionState peeraddr peerconn] → ShowS Source #

emptyPeerSelectionState ∷ StdGen → PeerSelectionState peeraddr peerconn Source #

assertPeerSelectionStateOrd peeraddr ⇒ PeerSelectionState peeraddr peerconn → a → a Source #

establishedPeersStatusOrd peeraddr ⇒ PeerSelectionState peeraddr peerconn → Map peeraddr PeerStatus Source #

A view of the status of each established peer, for testing and debugging.

data Guarded m a Source #

The governor is using Guarded m (Decision m peeraddr peerconn) where m is an STM monad, to drive its progress.

Constructors

GuardedSkip !(Maybe (Min Time))

GuardedSkip is used to instruct that there is no action to be made by the governor.

Let us note that the combined value which is computed by guardedDecisions term in peerSelectionGovernorLoop will never return it: this is bacause there are monitoring decisions which never return this constructor, e.g. targetPeers, jobs, connections, and thus the governor has always something to do.

Bundled Patterns

pattern GuardedMaybe (Min Time) → m a → Guarded m a

Guarded constructor which provides an action, possibly with a timeout, to the governor main loop. It hides the use of FirstToFinish synchronisation.

Instances

Instances details
Alternative m ⇒ Semigroup (Guarded m a) Source #

Guarded constructor is absorbing in the sense that

Guarded x y <> a = Guarded x' y'
a <> Guarded x y = Guarded x' y'

In the algebraic sense, Guarded (Just minBound) (return x) is a left absorbing element when "m ~ STM m' for some monad m'. There is no right absorbing element since there is no right absorbing elemnt in STM m'@.

Ref. absorbing element

Instance details

Defined in Ouroboros.Network.PeerSelection.Governor.Types

Methods

(<>)Guarded m a → Guarded m a → Guarded m a Source #

sconcatNonEmpty (Guarded m a) → Guarded m a Source #

stimesIntegral b ⇒ b → Guarded m a → Guarded m a Source #

data Decision m peeraddr peerconn Source #

Constructors

Decision 

Fields

type TimedDecision m peeraddr peerconn = Time → Decision m peeraddr peerconn Source #

Decision which has access to the current time, rather than the time when the governor's loop blocked to make a decision.

type MkGuardedDecision peeraddr peerconn m = PeerSelectionPolicy peeraddr m → PeerSelectionState peeraddr peerconn → Guarded (STM m) (TimedDecision m peeraddr peerconn) Source #

Type alias for function types which are used to create governor decisions. Allmost all decisions are following this pattern.

newtype Completion m peeraddr peerconn Source #

Constructors

Completion (PeerSelectionState peeraddr peerconn → Time → Decision m peeraddr peerconn) 

Traces

data TracePeerSelection peeraddr Source #

Constructors

TraceLocalRootPeersChanged (LocalRootPeers peeraddr) (LocalRootPeers peeraddr) 
TraceTargetsChanged PeerSelectionTargets PeerSelectionTargets 
TracePublicRootsRequest Int Int 
TracePublicRootsResults (Set peeraddr) Int DiffTime 
TracePublicRootsFailure SomeException Int DiffTime 
TraceGossipRequests Int Int (Set peeraddr) (Set peeraddr)

target known peers, actual known peers, peers available for gossip, peers selected for gossip

TraceGossipResults [(peeraddr, Either SomeException [peeraddr])] 
TraceForgetColdPeers Int Int (Set peeraddr)

target known peers, actual known peers, selected peer

TracePromoteColdPeers Int Int (Set peeraddr)

target established, actual established, selected peers

TracePromoteColdLocalPeers Int Int (Set peeraddr)

target local established, actual local established, selected peers

TracePromoteColdFailed Int Int peeraddr DiffTime SomeException

target established, actual established, peer, delay until next promotion, reason

TracePromoteColdDone Int Int peeraddr

target established, actual established, peer

TracePromoteWarmPeers Int Int (Set peeraddr)

target active, actual active, selected peers

TracePromoteWarmLocalPeers [(Int, Int)] (Set peeraddr)

local per-group (target active, actual active), selected peers

TracePromoteWarmFailed Int Int peeraddr SomeException

target active, actual active, peer, reason

TracePromoteWarmDone Int Int peeraddr

target active, actual active, peer

TracePromoteWarmAborted Int Int peeraddr

aborted promotion of a warm peer; likely it was asynchronously demoted in the meantime.

target active, actual active, peer

TraceDemoteWarmPeers Int Int (Set peeraddr)

target established, actual established, selected peers

TraceDemoteWarmFailed Int Int peeraddr SomeException

target established, actual established, peer, reason

TraceDemoteWarmDone Int Int peeraddr

target established, actual established, peer

TraceDemoteHotPeers Int Int (Set peeraddr)

target active, actual active, selected peers

TraceDemoteLocalHotPeers [(Int, Int)] (Set peeraddr)

local per-group (target active, actual active), selected peers

TraceDemoteHotFailed Int Int peeraddr SomeException

target active, actual active, peer, reason

TraceDemoteHotDone Int Int peeraddr

target active, actual active, peer

TraceDemoteAsynchronous (Map peeraddr PeerStatus) 
TraceGovernorWakeup 
TraceChurnWait DiffTime 
TraceChurnMode ChurnMode 

Instances

Instances details
(Show peeraddr, Ord peeraddr) ⇒ Show (TracePeerSelection peeraddr) Source # 
Instance details

Defined in Ouroboros.Network.PeerSelection.Governor.Types

Methods

showsPrecIntTracePeerSelection peeraddr → ShowS Source #

showTracePeerSelection peeraddr → String Source #

showList ∷ [TracePeerSelection peeraddr] → ShowS Source #

data DebugPeerSelection peeraddr peerconn Source #

Constructors

TraceGovernorState Time (Maybe DiffTime) (PeerSelectionState peeraddr peerconn) 

Instances

Instances details
Functor (DebugPeerSelection peeraddr) Source # 
Instance details

Defined in Ouroboros.Network.PeerSelection.Governor.Types

Methods

fmap ∷ (a → b) → DebugPeerSelection peeraddr a → DebugPeerSelection peeraddr b Source #

(<$) ∷ a → DebugPeerSelection peeraddr b → DebugPeerSelection peeraddr a Source #

(Ord peeraddr, Show peeraddr, Show peerconn) ⇒ Show (DebugPeerSelection peeraddr peerconn) Source # 
Instance details

Defined in Ouroboros.Network.PeerSelection.Governor.Types

Methods

showsPrecIntDebugPeerSelection peeraddr peerconn → ShowS Source #

showDebugPeerSelection peeraddr peerconn → String Source #

showList ∷ [DebugPeerSelection peeraddr peerconn] → ShowS Source #