From 08be124619076cdfee795114dd045426067e5966 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Facundo=20Dom=C3=ADnguez?= Date: Wed, 26 Jun 2024 12:39:26 -0300 Subject: [PATCH] Documentation edits for CSJ MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Mention that the objector also gets demoted * Edit note on Interactions with the BlockFetch logic * Expand the comments motivating DynamoInitState and ObjectorInitState Co-authored-by: Nicolas “Niols” Jeannerod --- .../MiniProtocol/ChainSync/Client/Jumping.hs | 23 +++++++++++-------- .../MiniProtocol/ChainSync/Client/State.hs | 12 +++++++--- 2 files changed, 22 insertions(+), 13 deletions(-) diff --git a/ouroboros-consensus/src/ouroboros-consensus/Ouroboros/Consensus/MiniProtocol/ChainSync/Client/Jumping.hs b/ouroboros-consensus/src/ouroboros-consensus/Ouroboros/Consensus/MiniProtocol/ChainSync/Client/Jumping.hs index 2606cf76f0..ad76dba48c 100644 --- a/ouroboros-consensus/src/ouroboros-consensus/Ouroboros/Consensus/MiniProtocol/ChainSync/Client/Jumping.hs +++ b/ouroboros-consensus/src/ouroboros-consensus/Ouroboros/Consensus/MiniProtocol/ChainSync/Client/Jumping.hs @@ -77,9 +77,10 @@ -- Interactions with the BlockFetch logic -- -------------------------------------- -- --- When syncing, the BlockFetch logic will fetch blocks from the dynamo. If the --- dynamo is responding too slowly, the BlockFetch logic can ask to change the --- dynamo with a call to 'rotateDynamo'. +-- When syncing, the BlockFetch logic might request to change the dynamo with +-- a call to 'rotateDynamo'. This is because the choice of dynamo influences +-- which peer is selected to download blocks. See the note "Interactions with +-- ChainSync Jumping" in "Ouroboros.Network.BlockFetch.Decision.BulkSync". -- -- Interactions with the Limit on Patience -- --------------------------------------- @@ -155,8 +156,9 @@ -- (j|k). -- -- The BlockFetch logic can ask to change the dynamo if it is not serving blocks --- fast enough. If there are other non-disengaged peers the dynamo is demoted to --- a jumper (l) and a new dynamo is elected. +-- fast enough. If there are other non-disengaged peers, the dynamo (and the +-- objector if there is one) is demoted to a jumper (l+g) and a new dynamo is +-- elected. -- module Ouroboros.Consensus.MiniProtocol.ChainSync.Client.Jumping ( Context @@ -275,9 +277,9 @@ mkJumping peerContext = Jumping -- -- Invariants: -- --- - If 'handlesCol is not empty, then there is exactly one dynamo in it. --- - There is at most one objector in 'handlesCol. --- - If there exist 'FoundIntersection' jumpers in 'handlesCol, then there +-- - If 'handlesCol' is not empty, then there is exactly one dynamo in it. +-- - There is at most one objector in 'handlesCol'. +-- - If there exist 'FoundIntersection' jumpers in 'handlesCol', then there -- is an objector and the intersection of the objector with the dynamo is -- at least as old as the oldest intersection of the `FoundIntersection` jumpers -- with the dynamo. @@ -763,8 +765,9 @@ unregisterClient context = do Objector{} -> electNewObjector context' Dynamo{} -> void $ electNewDynamo context' --- | Elects a new dynamo by demoting the given dynamo to a jumper, moving the --- peer to the end of the queue of chain sync handles and electing a new dynamo. +-- | Elects a new dynamo by demoting the given dynamo (and the objector if there +-- is one) to a jumper, moving the peer to the end of the queue of chain sync +-- handles and electing a new dynamo. -- -- It does nothing if there is no other engaged peer to elect or if the given -- peer is not the dynamo. diff --git a/ouroboros-consensus/src/ouroboros-consensus/Ouroboros/Consensus/MiniProtocol/ChainSync/Client/State.hs b/ouroboros-consensus/src/ouroboros-consensus/Ouroboros/Consensus/MiniProtocol/ChainSync/Client/State.hs index 69fa5ea7cd..763e79fd89 100644 --- a/ouroboros-consensus/src/ouroboros-consensus/Ouroboros/Consensus/MiniProtocol/ChainSync/Client/State.hs +++ b/ouroboros-consensus/src/ouroboros-consensus/Ouroboros/Consensus/MiniProtocol/ChainSync/Client/State.hs @@ -165,8 +165,11 @@ newChainSyncClientHandleCollection = do } data DynamoInitState blk - = -- | The dynamo has not yet started jumping and we first need to jump to the - -- given jump info to set the intersection of the ChainSync server. + = -- | The dynamo still has to set the intersection of the ChainSync server + -- before it can resume downloading headers. This is because + -- the message pipeline might be drained to do jumps, and this causes + -- the intersection on the ChainSync server to diverge from the tip of + -- the candidate fragment. DynamoStarting !(JumpInfo blk) | DynamoStarted deriving (Generic) @@ -179,7 +182,10 @@ deriving anyclass instance data ObjectorInitState = -- | The objector still needs to set the intersection of the ChainSync - -- server before resuming retrieval of headers. + -- server before resuming retrieval of headers. This is mainly because + -- the message pipeline might be drained to do jumps, and this causes + -- the intersection on the ChainSync server to diverge from the tip of + -- the candidate fragment. Starting | Started deriving (Generic, Show, NoThunks)