| Safe Haskell | None |
|---|---|
| Language | Haskell2010 |
Ouroboros.Consensus.Storage.LedgerDB.OnDisk
Synopsis
- initLedgerDB :: forall m blk. (IOLike m, LedgerSupportsProtocol blk, InspectLedger blk, HasCallStack) => Tracer m (TraceReplayEvent blk ()) -> Tracer m (TraceEvent blk) -> SomeHasFS m -> (forall s. Decoder s (ExtLedgerState blk)) -> (forall s. Decoder s (RealPoint blk)) -> LedgerDbParams -> ExtLedgerCfg blk -> m (ExtLedgerState blk) -> StreamAPI m blk -> m (InitLog blk, LedgerDB' blk, Word64)
- data InitLog blk
- = InitFromGenesis
- | InitFromSnapshot DiskSnapshot (Point blk)
- | InitFailure DiskSnapshot (InitFailure blk) (InitLog blk)
- data InitFailure blk
- type LedgerDB' blk = LedgerDB (ExtLedgerState blk) (RealPoint blk)
- ledgerDbTip' :: LedgerDB' blk -> Point blk
- type ChainSummary' blk = ChainSummary (ExtLedgerState blk) (RealPoint blk)
- csTip' :: ChainSummary' blk -> Point blk
- type AnnLedgerError' blk = AnnLedgerError (ExtLedgerState blk) (RealPoint blk)
- data NextBlock blk
- = NoMoreBlocks
- | NextBlock blk
- data StreamAPI m blk = StreamAPI {
- streamAfter :: forall a. HasCallStack => Point blk -> (Maybe (m (NextBlock blk)) -> m a) -> m a
- takeSnapshot :: forall m blk. MonadThrow m => Tracer m (TraceEvent blk) -> SomeHasFS m -> (ExtLedgerState blk -> Encoding) -> (RealPoint blk -> Encoding) -> LedgerDB' blk -> m (DiskSnapshot, Point blk)
- trimSnapshots :: Monad m => Tracer m (TraceEvent r) -> SomeHasFS m -> DiskPolicy -> m [DiskSnapshot]
- data DiskSnapshot
- deleteSnapshot :: HasCallStack => SomeHasFS m -> DiskSnapshot -> m ()
- snapshotToPath :: DiskSnapshot -> FsPath
- data TraceEvent blk
- data TraceReplayEvent blk replayTo
- = ReplayFromGenesis replayTo
- | ReplayFromSnapshot DiskSnapshot (Point blk) replayTo
- | ReplayedBlock (RealPoint blk) [LedgerEvent blk] replayTo
Opening the database
Arguments
| :: forall m blk. (IOLike m, LedgerSupportsProtocol blk, InspectLedger blk, HasCallStack) | |
| => Tracer m (TraceReplayEvent blk ()) | |
| -> Tracer m (TraceEvent blk) | |
| -> SomeHasFS m | |
| -> (forall s. Decoder s (ExtLedgerState blk)) | |
| -> (forall s. Decoder s (RealPoint blk)) | |
| -> LedgerDbParams | |
| -> ExtLedgerCfg blk | |
| -> m (ExtLedgerState blk) | Genesis ledger state |
| -> StreamAPI m blk | |
| -> m (InitLog blk, LedgerDB' blk, Word64) |
Initialize the ledger DB from the most recent snapshot on disk
If no such snapshot can be found, use the genesis ledger DB. Returns the initialized DB as well as the block reference corresponding to the snapshot we found on disk (the latter primarily for testing/monitoring purposes).
We do not catch any exceptions thrown during streaming; should any be
thrown, it is the responsibility of the ChainDB to catch these
and trigger (further) validation. We only discard snapshots if
- We cannot deserialise them, or
- they are ahead of the chain
It is possible that the Ledger DB will not be able to roll back k blocks
after initialization if the chain has been truncated (data corruption).
Initialization log
The initialization log records which snapshots from disk were considered, in which order, and why some snapshots were rejected. It is primarily useful for monitoring purposes.
Constructors
| InitFromGenesis | Defaulted to initialization from genesis NOTE: Unless the blockchain is near genesis, we should see this only if data corrupted occurred. |
| InitFromSnapshot DiskSnapshot (Point blk) | Used a snapshot corresponding to the specified tip |
| InitFailure DiskSnapshot (InitFailure blk) (InitLog blk) | Initialization skipped a snapshot We record the reason why it was skipped. NOTE: We should only see this if data corrupted occurred. |
Instances
data InitFailure blk Source #
Constructors
| InitFailureRead ReadIncrementalErr | We failed to deserialise the snapshot This can happen due to data corruption in the ledger DB. |
| InitFailureTooRecent (Point blk) | This snapshot is too recent (ahead of the tip of the chain) |
Instances
Instantiate in-memory to blk
ledgerDbTip' :: LedgerDB' blk -> Point blk Source #
type ChainSummary' blk = ChainSummary (ExtLedgerState blk) (RealPoint blk) Source #
csTip' :: ChainSummary' blk -> Point blk Source #
type AnnLedgerError' blk = AnnLedgerError (ExtLedgerState blk) (RealPoint blk) Source #
Abstraction over the stream API
Next block returned during streaming
Constructors
| NoMoreBlocks | |
| NextBlock blk |
Stream blocks from the immutable DB
When we initialize the ledger DB, we try to find a snapshot close to the tip of the immutable DB, and then stream blocks from the immutable DB to its tip to bring the ledger up to date with the tip of the immutable DB.
In CPS form to enable the use of withXYZ style iterator init functions.
Constructors
| StreamAPI | |
Fields
| |
Write to disk
takeSnapshot :: forall m blk. MonadThrow m => Tracer m (TraceEvent blk) -> SomeHasFS m -> (ExtLedgerState blk -> Encoding) -> (RealPoint blk -> Encoding) -> LedgerDB' blk -> m (DiskSnapshot, Point blk) Source #
Take a snapshot of the oldest ledger state in the ledger DB
We write the oldest ledger state to disk because the intention is to only
write ledger states to disk that we know to be immutable. Primarily for
testing purposes, takeSnapshot returns the block reference corresponding
to the snapshot that we wrote.
NOTE: This is a lower-level API that unconditionally takes a snapshot
(i.e., independent from whether this snapshot corresponds to a state that
is more than k back).
TODO: Should we delete the file if an error occurs during writing?
trimSnapshots :: Monad m => Tracer m (TraceEvent r) -> SomeHasFS m -> DiskPolicy -> m [DiskSnapshot] Source #
Trim the number of on disk snapshots so that at most onDiskNumSnapshots
snapshots are stored on disk. The oldest snapshots are deleted.
The deleted snapshots are returned.
Low-level API (primarily exposed for testing)
data DiskSnapshot Source #
On disk snapshots are numbered monotonically
Instances
deleteSnapshot :: HasCallStack => SomeHasFS m -> DiskSnapshot -> m () Source #
Delete snapshot from disk
snapshotToPath :: DiskSnapshot -> FsPath Source #
Trace events
data TraceEvent blk Source #
Constructors
| InvalidSnapshot DiskSnapshot (InitFailure blk) | An on disk snapshot was skipped because it was invalid. |
| TookSnapshot DiskSnapshot (Point blk) | A snapshot was written to disk. |
| DeletedSnapshot DiskSnapshot | An old or invalid on-disk snapshot was deleted |
Instances
data TraceReplayEvent blk replayTo Source #
Events traced while replaying blocks against the ledger to bring it up to date w.r.t. the tip of the ImmutableDB during initialisation. As this process takes a while, we trace events to inform higher layers of our progress.
The replayTo parameter is meant to be filled in by a higher layer,
i.e., the ChainDB.
Constructors
| ReplayFromGenesis replayTo | There were no LedgerDB snapshots on disk, so we're replaying all blocks starting from Genesis against the initial ledger. The |
| ReplayFromSnapshot DiskSnapshot (Point blk) replayTo | There was a LedgerDB snapshot on disk corresponding to the given tip. We're replaying more recent blocks against it. The |
| ReplayedBlock (RealPoint blk) [LedgerEvent blk] replayTo | We replayed the given block (reference) on the genesis snapshot during the initialisation of the LedgerDB. The |