Rework "Resource management in the ChainDB"

Author: dnadales

ouroboros-consensus/src/ouroboros-consensus/Ouroboros/Consensus/Storage/ChainDB.hs

@@ -38,48 +38,57 @@
 --   chain. 'Ouroboros.Consensus.Storage.ChainDB.API.ChainDB' defines the chain
 --   DB API.
 --
--- == Resource management in the ChainDB
+-- == Resource Management in the ChainDB
 --
--- Each of the databases in the ChainDB can produce resources that need to be
--- eventually freed. In particular:
+-- Clients of the ChainDB can allocate resources from the databases
+-- it contains (LedgerDB, VolatileDB, and ImmutableDB):
 --
--- - The LedgerDB is used to create 'Forker's
+-- - The LedgerDB is used to create 'Forker's.
 --
 -- - The ChainDB is used to create 'Follower's (which in turn contain
 --   'Iterator's).
 --
--- The 'runWith' function in Consensus spawns a resource registry (which we will
--- name __the consensus registry__) which will contain the ChainDB. Shutting
--- down the Consensus layer is what will close the ChainDB by the consensus
--- resource registry going out of scope.
+-- These resources must eventually be freed.
 --
--- The resources above will be created by clients of the databases, not the
--- databases themselves. For example, it is Chain selection the one that opens a
--- forker using the LedgerDB. This in particular means that any clients that
--- create these resources will be created later than the database.
+-- The 'runWith' function in Consensus spawns a resource registry
+-- (which we will refer to as __the consensus registry__) that will include
+-- the ChainDB as one of its resources. When the Consensus layer is
+-- shut down, the consensus resource registry will exit the scope of
+-- the 'withRegistry' function. This causes all resources allocated
+-- in the registry —including the ChainDB— to be closed.
 --
--- We rely on a specific sequence of events for this schema to be correct:
+-- The resources mentioned above are created by clients of the ChainDB
+-- databases (LedgerDB, VolatileDB, and ImmutableDB), not by the
+-- databases themselves. For example, chain selection opens a
+-- forker using the LedgerDB. Crucially, this means that clients creating
+-- these resources are instantiated after the ChainDB.
+--
+-- We rely on a specific sequence of events for this design to be correct:
 --
 -- - The ChainDB is only closed by exiting the scope of the consensus
 --   resource registry.
 --
--- - If a client that can create resources is forked into a separate thread,
---   such thread is linked to the consensus registry. That way, it will be
---   deallocated before the ChainDB is closed, and its internal registry will
---   release any resources created in the client.
+-- - If a client creates resources tied to any of the
+--   aforementioned databases and is forked into a separate thread,
+--   that thread is linked to the consensus registry. Because resources
+--   in a registry are deallocated in reverse order of allocation, any
+--   resources created by such threads will be deallocated before the
+--   ChainDB is closed, ensuring proper cleanup.
 --
--- At the moment, we have two different approaches to resources and closing of
--- the databases:
+-- Currently, we have two distinct approaches to resource management
+-- and database closure:
 --
--- - In the LedgerDB, closing the database does not close any of the resources
---   but makes them unable to do any action other than being freed. See
---   'ldbForkers'.
+-- - In the LedgerDB, closing the database does not close any resources
+--   created by its clients. We rely on the resource registry to deallocate
+--   these resources before the LedgerDB is closed. However, after closing
+--   the LedgerDB, the only permitted action on these resources is to free them.
+--   See 'ldbForkers'.
 --
--- - In the ChainDB, closing the database does close all the followers and
+-- - In the ChainDB, closing the database also closes all followers and
 --   iterators.
 --
--- Ideally, we would change the ChainDB to follow the same approach as the
--- LedgerDB.
+-- TODO: Ideally, the ChainDB and LedgerDB should follow a consistent
+-- approach to resource deallocation.
 module Ouroboros.Consensus.Storage.ChainDB
   ( module Ouroboros.Consensus.Storage.ChainDB.API
   , module Ouroboros.Consensus.Storage.ChainDB.Impl