|
38 | 38 | -- chain. 'Ouroboros.Consensus.Storage.ChainDB.API.ChainDB' defines the chain |
39 | 39 | -- DB API. |
40 | 40 | -- |
41 | | --- NOTE: at the moment there is an inconsistency in the module structure for |
42 | | --- each of these components. In particular, |
43 | | --- "Ouroboros.Consensus.Storage.LedgerDB" contains the whole definition and API |
44 | | --- for the LedgerDB, but the other three databases are broken up into multiple |
45 | | --- smaller submodules. We aim to resolve this when UTxO-HD is merged. |
| 41 | +-- == Resource management in the ChainDB |
| 42 | +-- |
| 43 | +-- Each of the databases in the ChainDB can produce resources that need to be |
| 44 | +-- eventually freed. In particular: |
| 45 | +-- |
| 46 | +-- - The LedgerDB is used to create 'Forker's |
| 47 | +-- |
| 48 | +-- - The ChainDB is used to create 'Follower's (which in turn contain |
| 49 | +-- 'Iterator's). |
| 50 | +-- |
| 51 | +-- The 'runWith' function in Consensus spawns a resource registry (which we will |
| 52 | +-- name __the consensus registry__) which will contain the ChainDB. Shutting |
| 53 | +-- down the Consensus layer is what will close the ChainDB by the consensus |
| 54 | +-- resource registry going out of scope. |
| 55 | +-- |
| 56 | +-- The resources above will be created by clients of the databases, not the |
| 57 | +-- databases themselves. For example, it is Chain selection the one that opens a |
| 58 | +-- forker using the LedgerDB. This in particular means that any clients that |
| 59 | +-- create these resources will be created later than the database. |
| 60 | +-- |
| 61 | +-- We rely on a specific sequence of events for this schema to be correct: |
| 62 | +-- |
| 63 | +-- - The ChainDB is only closed by exiting the scope of the consensus |
| 64 | +-- resource registry. |
| 65 | +-- |
| 66 | +-- - If a client that can create resources is forked into a separate thread, |
| 67 | +-- such thread is linked to the consensus registry. That way, it will be |
| 68 | +-- deallocated before the ChainDB is closed, and its internal registry will |
| 69 | +-- release any resources created in the client. |
| 70 | +-- |
| 71 | +-- At the moment, we have two different approaches to resources and closing of |
| 72 | +-- the databases: |
| 73 | +-- |
| 74 | +-- - In the LedgerDB, closing the database does not close any of the resources |
| 75 | +-- but makes them unable to do any action other than being freed. See |
| 76 | +-- 'ldbForkers'. |
| 77 | +-- |
| 78 | +-- - In the ChainDB, closing the database does close all the followers and |
| 79 | +-- iterators. |
| 80 | +-- |
| 81 | +-- Ideally, we would change the ChainDB to follow the same approach as the |
| 82 | +-- LedgerDB. |
46 | 83 | module Ouroboros.Consensus.Storage.ChainDB |
47 | 84 | ( module Ouroboros.Consensus.Storage.ChainDB.API |
48 | 85 | , module Ouroboros.Consensus.Storage.ChainDB.Impl |
|
0 commit comments