ouroboros-network-0.16.1.0: A networking layer for the Ouroboros blockchain protocol
Safe HaskellSafe-Inferred
LanguageHaskell2010

Ouroboros.Network.BlockFetch.State

Synopsis

Documentation

fetchLogicIterations ∷ (HasHeader header, HasHeader block, HeaderHash header ~ HeaderHash block, MonadDelay m, MonadSTM m, Ord peer, Hashable peer) ⇒ Tracer m [TraceLabelPeer peer (FetchDecision [Point header])] → Tracer m (TraceLabelPeer peer (TraceFetchClientState header)) → FetchDecisionPolicy header → FetchTriggerVariables peer header m → FetchNonTriggerVariables peer header block m → m Void Source #

data FetchTriggerVariables peer header m Source #

STM actions to read various state variables that the fetch logic depends upon. Any change in these variables is a trigger to re-evaluate the decision on what blocks to fetch.

Note that this is a "level trigger" not an "edge trigger": we do not have to re-evaluate on every change, it is sufficient to re-evaluate at some stage after one or more changes. This means it is ok to get somewhat behind, and it is not necessary to determine exactly what changed, just that there was some change.

data FetchNonTriggerVariables peer header block m Source #

STM actions to read various state variables that the fetch logic uses. While the decisions do make use of the values of these variables, it is not necessary to re-evaluate when these variables change.

type FetchDecision result = Either FetchDecline result Source #

Throughout the decision making process we accumulate reasons to decline to fetch any blocks. This type is used to wrap intermediate and final results.

data FetchDecline Source #

All the various reasons we can decide not to fetch blocks from a peer.

It is worth highlighting which of these reasons result from competition among upstream peers.

  • FetchDeclineInFlightOtherPeer: decline this peer because all the unfetched blocks of its candidate chain have already been requested from other peers. This reason reflects the least-consequential competition among peers: the competition that determines merely which upstream peer to burden with the request (eg the one with the best DeltaQ metrics). The consequences are relatively minor because the unfetched blocks on this peer's candidate chain will be requested regardless; it's merely a question of "From who?". (One exception: if an adversarial peer wins this competition such that the blocks are only requested from them, then it may be possible that this decision determines whether the blocks are ever received. But that depends on details of timeouts, a longer competing chain being soon received within those timeouts, and so on.)
  • FetchDeclineChainNotPlausible: decline this peer because the node has already fetched, validated, and selected a chain better than its candidate chain from other peers (or from the node's own block forge). Because the node's current selection is influenced by what blocks other peers have recently served (or it recently minted), this reason reflects that peers indirectly compete by serving as long of a chain as possible and as promptly as possible. When the tips of the peers' selections are all within their respective forecast horizons (see ledgerViewForecastAt), then the length of their candidate chains will typically be the length of their selections, since the ChainSync is free to race ahead (in contrast, the BlockFetch pipeline depth is bounded such that it will, for a syncing node, not be able to request all blocks between the selection and the end of the forecast window). But if one or more of their tips is beyond the horizon, then the relative length of the candidate chains is more complicated, influenced by both the relative density of the chains' suffixes and the relative age of the chains' intersection with the node's selection (since each peer's forecast horizon is a fixed number of slots after the candidate's successor of that intersection).
  • FetchDeclineConcurrencyLimit: decline this peer while the node has already fully allocated the artificially scarce maxConcurrentFetchPeers resource amongst its other peers. This reason reflects the least-fundamental competition: it's the only way a node would decline a candidate chain C that it would immediately switch to if C had somehow already been fetched (and any better current candidates hadn't). It is possible that this peer's candidate fragment is better than the candidate fragments of other peers, but that should only happen ephemerally (eg for a brief while immediately after first connecting to this peer).
  • FetchDeclineChainIntersectionTooDeep: decline this peer because the node's selection has more than K blocks that are not on this peer's candidate chain. Typically, this reason occurs after the node has been declined---ie lost the above competitions---for a long enough duration. This decision only arises if the BlockFetch decision logic wins a harmless race against the ChainSync client once the node's selection gets longer, since ForkTooDeep disconnects from such a peer.

Constructors

FetchDeclineChainNotPlausible

This peer's candidate chain is not longer than our chain. For more details see mkBlockFetchConsensusInterface which implements plausibleCandidateChain.

FetchDeclineChainIntersectionTooDeep

Switching to this peer's candidate chain would require rolling back more than K blocks.

FetchDeclineAlreadyFetched

Every block on this peer's candidate chain has already been fetched.

FetchDeclineInFlightThisPeer

This peer's candidate chain has already been requested from this peer.

FetchDeclineInFlightOtherPeer

Some blocks on this peer's candidate chain have not yet been fetched, but all of those have already been requested from other peers.

FetchDeclinePeerShutdown

This peer's BlockFetch client is shutting down, see PeerFetchStatusShutdown.

FetchDeclinePeerStarting

Blockfetch is starting up and waiting on corresponding Chainsync.

FetchDeclinePeerSlow

This peer is in a potentially-temporary state in which it has not responded to us within a certain expected time limit, see PeerFetchStatusAberrant.

FetchDeclineReqsInFlightLimit !Word

This peer is not under the maxInFlightReqsPerPeer limit.

The argument is the maxInFlightReqsPerPeer constant.

FetchDeclineBytesInFlightLimit !SizeInBytes !SizeInBytes !SizeInBytes

This peer is not under the inFlightBytesHighWatermark bytes limit.

The arguments are:

FetchDeclinePeerBusy !SizeInBytes !SizeInBytes !SizeInBytes

This peer is not under the inFlightBytesLowWatermark.

The arguments are:

FetchDeclineConcurrencyLimit !FetchMode !Word

The node is not under the maxConcurrentFetchPeers limit.

The arguments are:

Instances

Instances details
Show FetchDecline Source # 
Instance details

Defined in Ouroboros.Network.BlockFetch.Decision

Eq FetchDecline Source # 
Instance details

Defined in Ouroboros.Network.BlockFetch.Decision

data FetchMode Source #

Constructors

FetchModeBulkSync

Use this mode when we are catching up on the chain but are stil well behind. In this mode the fetch logic will optimise for throughput rather than latency.

FetchModeDeadline

Use this mode for block-producing nodes that have a known deadline to produce a block and need to get the best chain before that. In this mode the fetch logic will optimise for picking the best chain within the given deadline.

Instances

Instances details
Show FetchMode 
Instance details

Defined in Ouroboros.Network.BlockFetch.ConsensusInterface

Methods

showsPrecIntFetchModeShowS #

showFetchModeString #

showList ∷ [FetchMode] → ShowS #

Eq FetchMode 
Instance details

Defined in Ouroboros.Network.BlockFetch.ConsensusInterface

Methods

(==)FetchModeFetchModeBool #

(/=)FetchModeFetchModeBool #

data TraceLabelPeer peerid a Source #

A peer label for use in Tracers. This annotates tracer output as being associated with a given peer identifier.

Constructors

TraceLabelPeer peerid a 

Instances

Instances details
Bifunctor TraceLabelPeer 
Instance details

Defined in Network.Mux.Trace

Methods

bimap ∷ (a → b) → (c → d) → TraceLabelPeer a c → TraceLabelPeer b d #

first ∷ (a → b) → TraceLabelPeer a c → TraceLabelPeer b c #

second ∷ (b → c) → TraceLabelPeer a b → TraceLabelPeer a c #

Functor (TraceLabelPeer peerid) 
Instance details

Defined in Network.Mux.Trace

Methods

fmap ∷ (a → b) → TraceLabelPeer peerid a → TraceLabelPeer peerid b #

(<$) ∷ a → TraceLabelPeer peerid b → TraceLabelPeer peerid a #

(Show peerid, Show a) ⇒ Show (TraceLabelPeer peerid a) 
Instance details

Defined in Network.Mux.Trace

Methods

showsPrecIntTraceLabelPeer peerid a → ShowS #

showTraceLabelPeer peerid a → String #

showList ∷ [TraceLabelPeer peerid a] → ShowS #

(Eq peerid, Eq a) ⇒ Eq (TraceLabelPeer peerid a) 
Instance details

Defined in Network.Mux.Trace

Methods

(==)TraceLabelPeer peerid a → TraceLabelPeer peerid a → Bool #

(/=)TraceLabelPeer peerid a → TraceLabelPeer peerid a → Bool #

data TraceFetchClientState header Source #

Tracing types for the various events that change the state (i.e. FetchClientStateVars) for a block fetch client.

Note that while these are all state changes, the AddedFetchRequest occurs in the decision thread while the other state changes occur in the block fetch client threads.

Constructors

AddedFetchRequest (FetchRequest header) (PeerFetchInFlight header) PeerFetchInFlightLimits (PeerFetchStatus header)

The block fetch decision thread has added a new fetch instruction consisting of one or more individual request ranges.

AcknowledgedFetchRequest (FetchRequest header)

Mark the point when the fetch client picks up the request added by the block fetch decision thread. Note that this event can happen fewer times than the AddedFetchRequest due to fetch request merging.

SendFetchRequest (AnchoredFragment header) PeerGSV

Mark the point when fetch request for a fragment is actually sent over the wire.

StartedFetchBatch (ChainRange (Point header)) (PeerFetchInFlight header) PeerFetchInFlightLimits (PeerFetchStatus header)

Mark the start of receiving a streaming batch of blocks. This will be followed by one or more CompletedBlockFetch and a final CompletedFetchBatch.

CompletedBlockFetch (Point header) (PeerFetchInFlight header) PeerFetchInFlightLimits (PeerFetchStatus header) NominalDiffTime SizeInBytes

Mark the completion of of receiving a single block within a streaming batch of blocks.

CompletedFetchBatch (ChainRange (Point header)) (PeerFetchInFlight header) PeerFetchInFlightLimits (PeerFetchStatus header)

Mark the successful end of receiving a streaming batch of blocks

RejectedFetchBatch (ChainRange (Point header)) (PeerFetchInFlight header) PeerFetchInFlightLimits (PeerFetchStatus header)

If the other peer rejects our request then we have this event instead of StartedFetchBatch and CompletedFetchBatch.

ClientTerminating Int

The client is terminating. Log the number of outstanding requests.

Instances

Instances details
(StandardHash header, Show header) ⇒ Show (TraceFetchClientState header) Source # 
Instance details

Defined in Ouroboros.Network.BlockFetch.ClientState