| Safe Haskell | Safe-Inferred |
|---|---|
| Language | Haskell2010 |
Ouroboros.Consensus.Storage.ImmutableDB.API
Synopsis
- data ImmutableDB m blk = ImmutableDB {
- closeDB_ ∷ HasCallStack ⇒ m ()
- getTip_ ∷ HasCallStack ⇒ STM m (WithOrigin (Tip blk))
- getBlockComponent_ ∷ ∀ b. HasCallStack ⇒ BlockComponent blk b → RealPoint blk → m (Either (MissingBlock blk) b)
- appendBlock_ ∷ HasCallStack ⇒ blk → m ()
- stream_ ∷ ∀ b. HasCallStack ⇒ ResourceRegistry m → BlockComponent blk b → StreamFrom blk → StreamTo blk → m (Either (MissingBlock blk) (Iterator m blk b))
- data Iterator m blk b = Iterator {
- iteratorNext ∷ HasCallStack ⇒ m (IteratorResult b)
- iteratorHasNext ∷ HasCallStack ⇒ STM m (Maybe (RealPoint blk))
- iteratorClose ∷ HasCallStack ⇒ m ()
- data IteratorResult b
- iteratorToList ∷ (HasCallStack, Monad m) ⇒ Iterator m blk b → m [b]
- traverseIterator ∷ Monad m ⇒ (b → m b') → Iterator m blk b → Iterator m blk b'
- newtype CompareTip blk = CompareTip {
- getCompareTip ∷ Tip blk
- type SecondaryOffset = Word32
- data Tip blk = Tip {
- tipSlotNo ∷ !SlotNo
- tipIsEBB ∷ !IsEBB
- tipBlockNo ∷ !BlockNo
- tipHash ∷ !(HeaderHash blk)
- blockToTip ∷ GetHeader blk ⇒ blk → Tip blk
- headerToTip ∷ GetHeader blk ⇒ Header blk → Tip blk
- tipToAnchor ∷ WithOrigin (Tip blk) → Anchor blk
- tipToPoint ∷ WithOrigin (Tip blk) → Point blk
- tipToRealPoint ∷ Tip blk → RealPoint blk
- data ApiMisuse blk
- = AppendBlockNotNewerThanTipError (RealPoint blk) (Point blk)
- | InvalidIteratorRangeError (StreamFrom blk) (StreamTo blk)
- | ClosedDBError
- | OpenDBError
- data ImmutableDBError blk
- = ApiMisuse (ApiMisuse blk) PrettyCallStack
- | UnexpectedFailure (UnexpectedFailure blk)
- data MissingBlock blk
- = EmptySlot (RealPoint blk) ChunkNo [RelativeSlot] (Maybe (StrictSeq SecondaryOffset))
- | WrongHash (RealPoint blk) (NonEmpty (HeaderHash blk))
- | NewerThanTip (RealPoint blk) (Point blk)
- data UnexpectedFailure blk
- = FileSystemError FsError
- | InvalidFileError FsPath String PrettyCallStack
- | MissingFileError FsPath PrettyCallStack
- | ChecksumMismatchError (RealPoint blk) CRC CRC FsPath PrettyCallStack
- | ParseError FsPath (RealPoint blk) DeserialiseFailure
- | TrailingDataError FsPath (RealPoint blk) ByteString
- | MissingBlockError (MissingBlock blk)
- | CorruptBlockError (RealPoint blk)
- missingBlockPoint ∷ MissingBlock blk → RealPoint blk
- throwApiMisuse ∷ (MonadThrow m, HasCallStack, StandardHash blk, Typeable blk) ⇒ ApiMisuse blk → m a
- throwUnexpectedFailure ∷ (StandardHash blk, Typeable blk, MonadThrow m) ⇒ UnexpectedFailure blk → m a
- appendBlock ∷ HasCallStack ⇒ ImmutableDB m blk → blk → m ()
- closeDB ∷ HasCallStack ⇒ ImmutableDB m blk → m ()
- getBlockComponent ∷ HasCallStack ⇒ ImmutableDB m blk → BlockComponent blk b → RealPoint blk → m (Either (MissingBlock blk) b)
- getTip ∷ HasCallStack ⇒ ImmutableDB m blk → STM m (WithOrigin (Tip blk))
- stream ∷ HasCallStack ⇒ ImmutableDB m blk → ResourceRegistry m → BlockComponent blk b → StreamFrom blk → StreamTo blk → m (Either (MissingBlock blk) (Iterator m blk b))
- getKnownBlockComponent ∷ (MonadThrow m, HasHeader blk) ⇒ ImmutableDB m blk → BlockComponent blk b → RealPoint blk → m b
- getTipAnchor ∷ (MonadSTM m, HasCallStack) ⇒ ImmutableDB m blk → STM m (Anchor blk)
- getTipPoint ∷ (MonadSTM m, HasCallStack) ⇒ ImmutableDB m blk → STM m (Point blk)
- getTipSlot ∷ (MonadSTM m, HasCallStack) ⇒ ImmutableDB m blk → STM m (WithOrigin SlotNo)
- hasBlock ∷ (MonadSTM m, HasCallStack) ⇒ ImmutableDB m blk → RealPoint blk → m Bool
- streamAfterKnownPoint ∷ (MonadSTM m, MonadThrow m, HasHeader blk, HasCallStack) ⇒ ImmutableDB m blk → ResourceRegistry m → BlockComponent blk b → Point blk → m (Iterator m blk b)
- streamAfterPoint ∷ (MonadSTM m, HasHeader blk, HasCallStack) ⇒ ImmutableDB m blk → ResourceRegistry m → BlockComponent blk b → Point blk → m (Either (MissingBlock blk) (Iterator m blk b))
- streamAll ∷ (MonadSTM m, MonadThrow m, HasHeader blk, HasCallStack) ⇒ ImmutableDB m blk → ResourceRegistry m → BlockComponent blk b → m (Iterator m blk b)
- withDB ∷ (HasCallStack, MonadThrow m) ⇒ m (ImmutableDB m blk) → (ImmutableDB m blk → m a) → m a
API
data ImmutableDB m blk Source #
API for the ImmutableDB.
The ImmutableDB stores blocks in SlotNos. Nevertheless, lookups use
RealPoint, primarily because Epoch Boundary Blocks (EBBs) have the same
SlotNo as the regular block after them (unless that slot is empty), so that
we have to use the hash of the block to distinguish the two (hence
RealPoint). But also to avoid reading the wrong block, i.e., when we expect
a block with a different hash.
The database is append-only, so you cannot append a block to a slot in the past. You can, however, skip slots, e.g., append to slot 0 and then to slot 5, but afterwards, you can no longer append to slots 1-4. You can only store at most one block in each slot, except for EBBs, which are stored separately, at the start of each epoch/chunk.
The block stored in a slot can be queried with getBlockComponent. Block
components can also be streamed using Iterators, see stream.
The Tip of the database can be queried with getTip. This tip will
always point to a filled slot or an EBB that is present.
The database can be explicitly closed, but can also be automatically closed
in case of an ImmutableDBError.
Constructors
| ImmutableDB | |
Fields
| |
Instances
| NoThunks (ImmutableDB m blk) Source # | |
Defined in Ouroboros.Consensus.Storage.ImmutableDB.API | |
Iterator API
data Iterator m blk b Source #
An Iterator is a handle which can be used to efficiently stream block
components from the ImmutableDB.
Constructors
| Iterator | |
Fields
| |
data IteratorResult b Source #
The result of stepping an Iterator.
Constructors
| IteratorExhausted | |
| IteratorResult b |
Instances
iteratorToList ∷ (HasCallStack, Monad m) ⇒ Iterator m blk b → m [b] Source #
Consume an Iterator by stepping until it is exhausted. A list of all
the IteratorResults (excluding the final IteratorExhausted) produced by
the Iterator is returned.
traverseIterator ∷ Monad m ⇒ (b → m b') → Iterator m blk b → Iterator m blk b' Source #
Variant of traverse instantiated to Iterator m blk miteratorNext.
Types
newtype CompareTip blk Source #
Constructors
| CompareTip | |
Fields
| |
Instances
| Eq (CompareTip blk) Source # | |
Defined in Ouroboros.Consensus.Storage.ImmutableDB.API Methods (==) ∷ CompareTip blk → CompareTip blk → Bool # (/=) ∷ CompareTip blk → CompareTip blk → Bool # | |
| Ord (CompareTip blk) Source # | |
Defined in Ouroboros.Consensus.Storage.ImmutableDB.API Methods compare ∷ CompareTip blk → CompareTip blk → Ordering # (<) ∷ CompareTip blk → CompareTip blk → Bool # (<=) ∷ CompareTip blk → CompareTip blk → Bool # (>) ∷ CompareTip blk → CompareTip blk → Bool # (>=) ∷ CompareTip blk → CompareTip blk → Bool # max ∷ CompareTip blk → CompareTip blk → CompareTip blk # min ∷ CompareTip blk → CompareTip blk → CompareTip blk # | |
type SecondaryOffset = Word32 Source #
An offset in the secondary index file.
We need 4 bytes (Word32) because the secondary index file can grow to
+1MiB.
Information about the tip of the ImmutableDB.
Constructors
| Tip | |
Fields
| |
Instances
| Generic (Tip blk) Source # | |
| StandardHash blk ⇒ Show (Tip blk) Source # | |
| StandardHash blk ⇒ Eq (Tip blk) Source # | |
| StandardHash blk ⇒ NoThunks (Tip blk) Source # | |
| type Rep (Tip blk) Source # | |
Defined in Ouroboros.Consensus.Storage.ImmutableDB.API type Rep (Tip blk) = D1 ('MetaData "Tip" "Ouroboros.Consensus.Storage.ImmutableDB.API" "ouroboros-consensus-0.21.0.0-inplace" 'False) (C1 ('MetaCons "Tip" 'PrefixI 'True) ((S1 ('MetaSel ('Just "tipSlotNo") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 SlotNo) :*: S1 ('MetaSel ('Just "tipIsEBB") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 IsEBB)) :*: (S1 ('MetaSel ('Just "tipBlockNo") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 BlockNo) :*: S1 ('MetaSel ('Just "tipHash") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 (HeaderHash blk))))) | |
blockToTip ∷ GetHeader blk ⇒ blk → Tip blk Source #
tipToAnchor ∷ WithOrigin (Tip blk) → Anchor blk Source #
tipToPoint ∷ WithOrigin (Tip blk) → Point blk Source #
tipToRealPoint ∷ Tip blk → RealPoint blk Source #
Errors
Constructors
| AppendBlockNotNewerThanTipError (RealPoint blk) (Point blk) | When trying to append a new block, it was not newer than the current tip, i.e., the slot was older than or equal to the current tip's slot. The |
| InvalidIteratorRangeError (StreamFrom blk) (StreamTo blk) | When the chosen iterator range was invalid, i.e. the |
| ClosedDBError | When performing an operation on a closed DB that is only allowed when the database is open. |
| OpenDBError | When performing an operation on an open DB that is only allowed when the database is closed. |
data ImmutableDBError blk Source #
Errors that might arise when working with this database.
Constructors
| ApiMisuse (ApiMisuse blk) PrettyCallStack | An error thrown because of incorrect usage of the immutable database by the user. |
| UnexpectedFailure (UnexpectedFailure blk) | An unexpected error thrown because something went wrong on a lower layer. |
Instances
data MissingBlock blk Source #
This type can be part of an exception, but also returned as part of an
Either, because it can be expected in some cases.
Constructors
| EmptySlot | There is no block in the slot of the given point. |
Fields
| |
| WrongHash (RealPoint blk) (NonEmpty (HeaderHash blk)) | The block and/or EBB in the slot of the given point have a different
hash. We return the |
| NewerThanTip (RealPoint blk) (Point blk) | The requested point is in the future, i.e., its slot is greater than that of the tip. We record the tip as the second argument. |
Instances
data UnexpectedFailure blk Source #
Constructors
| FileSystemError FsError | An IO operation on the file-system threw an error. |
| InvalidFileError FsPath String PrettyCallStack | When loading an epoch or index file, its contents did not pass validation. |
| MissingFileError FsPath PrettyCallStack | A missing epoch or index file. |
| ChecksumMismatchError (RealPoint blk) CRC CRC FsPath PrettyCallStack | There was a checksum mismatch when reading the block with the given
point. The first |
| ParseError FsPath (RealPoint blk) DeserialiseFailure | A block failed to parse |
| TrailingDataError FsPath (RealPoint blk) ByteString | When parsing a block we got some trailing data |
| MissingBlockError (MissingBlock blk) | Block missing This exception gets thrown when a block that we know it should be in the ImmutableDB, nonetheless was not found. |
| CorruptBlockError (RealPoint blk) | A (parsed) block did not pass the integrity check. This exception gets thrown when a block doesn't pass the integrity check
done for NOTE: we do not check the integrity of a block when it is added to the ImmutableDB. While this exception typically means the block has been corrupted, it could also mean the block didn't pass the check at the time it was added. |
Instances
| (StandardHash blk, Typeable blk) ⇒ Show (UnexpectedFailure blk) Source # | |
Defined in Ouroboros.Consensus.Storage.ImmutableDB.API Methods showsPrec ∷ Int → UnexpectedFailure blk → ShowS # show ∷ UnexpectedFailure blk → String # showList ∷ [UnexpectedFailure blk] → ShowS # | |
missingBlockPoint ∷ MissingBlock blk → RealPoint blk Source #
Return the RealPoint of the block that was missing.
throwApiMisuse ∷ (MonadThrow m, HasCallStack, StandardHash blk, Typeable blk) ⇒ ApiMisuse blk → m a Source #
throwUnexpectedFailure ∷ (StandardHash blk, Typeable blk, MonadThrow m) ⇒ UnexpectedFailure blk → m a Source #
Wrappers that preserve HasCallStack
appendBlock ∷ HasCallStack ⇒ ImmutableDB m blk → blk → m () Source #
closeDB ∷ HasCallStack ⇒ ImmutableDB m blk → m () Source #
getBlockComponent ∷ HasCallStack ⇒ ImmutableDB m blk → BlockComponent blk b → RealPoint blk → m (Either (MissingBlock blk) b) Source #
getTip ∷ HasCallStack ⇒ ImmutableDB m blk → STM m (WithOrigin (Tip blk)) Source #
stream ∷ HasCallStack ⇒ ImmutableDB m blk → ResourceRegistry m → BlockComponent blk b → StreamFrom blk → StreamTo blk → m (Either (MissingBlock blk) (Iterator m blk b)) Source #
Derived functionality
getKnownBlockComponent ∷ (MonadThrow m, HasHeader blk) ⇒ ImmutableDB m blk → BlockComponent blk b → RealPoint blk → m b Source #
getTipAnchor ∷ (MonadSTM m, HasCallStack) ⇒ ImmutableDB m blk → STM m (Anchor blk) Source #
getTipPoint ∷ (MonadSTM m, HasCallStack) ⇒ ImmutableDB m blk → STM m (Point blk) Source #
getTipSlot ∷ (MonadSTM m, HasCallStack) ⇒ ImmutableDB m blk → STM m (WithOrigin SlotNo) Source #
hasBlock ∷ (MonadSTM m, HasCallStack) ⇒ ImmutableDB m blk → RealPoint blk → m Bool Source #
streamAfterKnownPoint ∷ (MonadSTM m, MonadThrow m, HasHeader blk, HasCallStack) ⇒ ImmutableDB m blk → ResourceRegistry m → BlockComponent blk b → Point blk → m (Iterator m blk b) Source #
Variant of streamAfterPoint that throws a MissingBlockError when the
point is not in the ImmutableDB (or genesis).
streamAfterPoint ∷ (MonadSTM m, HasHeader blk, HasCallStack) ⇒ ImmutableDB m blk → ResourceRegistry m → BlockComponent blk b → Point blk → m (Either (MissingBlock blk) (Iterator m blk b)) Source #
Open an iterator with the given point as lower exclusive bound and the current tip as the inclusive upper bound.
Returns a MissingBlock when the point is not in the ImmutableDB.
streamAll ∷ (MonadSTM m, MonadThrow m, HasHeader blk, HasCallStack) ⇒ ImmutableDB m blk → ResourceRegistry m → BlockComponent blk b → m (Iterator m blk b) Source #
Arguments
| ∷ (HasCallStack, MonadThrow m) | |
| ⇒ m (ImmutableDB m blk) | How to open the database |
| → (ImmutableDB m blk → m a) | Action to perform using the database |
| → m a |
Open the database using the given function, perform the given action
using the database, and closes the database using its closeDB function,
in case of success or when an exception was raised.