| Safe Haskell | None |
|---|---|
| Language | Haskell2010 |
Ouroboros.Consensus.Storage.ImmutableDB.API
Synopsis
- data ImmutableDB m blk = ImmutableDB {
- closeDB_ :: HasCallStack => m ()
- getTip_ :: HasCallStack => STM m (WithOrigin (Tip blk))
- getBlockComponent_ :: forall b. HasCallStack => BlockComponent blk b -> RealPoint blk -> m (Either (MissingBlock blk) b)
- appendBlock_ :: HasCallStack => blk -> m ()
- stream_ :: forall 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
- traverseIterator :: Monad m => (b -> m b') -> Iterator m blk b -> Iterator m blk b'
- iteratorToList :: (HasCallStack, Monad m) => Iterator m blk b -> m [b]
- data Tip blk = Tip {
- tipSlotNo :: !SlotNo
- tipIsEBB :: !IsEBB
- tipBlockNo :: !BlockNo
- tipHash :: !(HeaderHash blk)
- tipToRealPoint :: Tip blk -> RealPoint blk
- tipToPoint :: WithOrigin (Tip blk) -> Point blk
- tipToAnchor :: WithOrigin (Tip blk) -> Anchor blk
- blockToTip :: (HasHeader blk, GetHeader blk) => blk -> Tip blk
- newtype CompareTip blk = CompareTip {
- getCompareTip :: Tip blk
- data ImmutableDBError
- data ApiMisuse
- = forall blk.(Typeable blk, StandardHash blk) => AppendBlockNotNewerThanTipError (RealPoint blk) (Point blk)
- | forall blk.(Typeable blk, StandardHash blk) => InvalidIteratorRangeError (StreamFrom blk) (StreamTo blk)
- | ClosedDBError
- | OpenDBError
- throwApiMisuse :: (MonadThrow m, HasCallStack) => ApiMisuse -> m a
- data UnexpectedFailure
- = FileSystemError FsError
- | InvalidFileError FsPath String PrettyCallStack
- | MissingFileError FsPath PrettyCallStack
- | forall blk.(Typeable blk, StandardHash blk) => ChecksumMismatchError (RealPoint blk) CRC CRC FsPath PrettyCallStack
- | forall blk.(Typeable blk, StandardHash blk) => ParseError FsPath (RealPoint blk) DeserialiseFailure
- | forall blk.(Typeable blk, StandardHash blk) => TrailingDataError FsPath (RealPoint blk) ByteString
- | forall blk.(Typeable blk, StandardHash blk) => MissingBlockError (MissingBlock blk)
- | forall blk.(Typeable blk, StandardHash blk) => CorruptBlockError (RealPoint blk)
- throwUnexpectedFailure :: MonadThrow m => UnexpectedFailure -> m a
- data MissingBlock blk
- = EmptySlot (RealPoint blk)
- | WrongHash (RealPoint blk) (NonEmpty (HeaderHash blk))
- | NewerThanTip (RealPoint blk) (Point blk)
- missingBlockPoint :: MissingBlock blk -> RealPoint blk
- closeDB :: HasCallStack => ImmutableDB m blk -> m ()
- getTip :: HasCallStack => ImmutableDB m blk -> STM m (WithOrigin (Tip blk))
- getBlockComponent :: HasCallStack => ImmutableDB m blk -> BlockComponent blk b -> RealPoint blk -> m (Either (MissingBlock blk) b)
- appendBlock :: HasCallStack => ImmutableDB m blk -> blk -> m ()
- stream :: HasCallStack => ImmutableDB m blk -> ResourceRegistry m -> BlockComponent blk b -> StreamFrom blk -> StreamTo blk -> m (Either (MissingBlock blk) (Iterator m blk b))
- withDB :: (HasCallStack, MonadThrow m) => m (ImmutableDB m blk) -> (ImmutableDB m blk -> m a) -> m a
- getKnownBlockComponent :: (MonadThrow m, HasHeader blk) => ImmutableDB m blk -> BlockComponent blk b -> RealPoint blk -> m b
- 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)
- hasBlock :: (MonadSTM m, HasCallStack) => ImmutableDB m blk -> RealPoint blk -> m Bool
- getTipPoint :: (MonadSTM m, HasCallStack) => ImmutableDB m blk -> STM m (Point blk)
- getTipAnchor :: (MonadSTM m, HasCallStack) => ImmutableDB m blk -> STM m (Anchor blk)
- getTipSlot :: (MonadSTM m, HasCallStack) => ImmutableDB m blk -> STM m (WithOrigin SlotNo)
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 UnexpectedFailure.
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
traverseIterator :: Monad m => (b -> m b') -> Iterator m blk b -> Iterator m blk b' Source #
Variant of traverse instantiated to Iterator m blk miteratorNext.
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.
Types
Information about the tip of the ImmutableDB.
Constructors
| Tip | |
Fields
| |
Instances
| StandardHash blk => Eq (Tip blk) Source # | |
| StandardHash blk => Show (Tip blk) Source # | |
| Generic (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.1.0.0-GfJNvFcM6lj2s5utKAUPEp" '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))))) | |
tipToRealPoint :: Tip blk -> RealPoint blk Source #
tipToPoint :: WithOrigin (Tip blk) -> Point blk Source #
tipToAnchor :: WithOrigin (Tip blk) -> Anchor blk Source #
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 # | |
Errors
data ImmutableDBError Source #
Errors that might arise when working with this database.
Constructors
| ApiMisuse ApiMisuse PrettyCallStack | An error thrown because of incorrect usage of the immutable database by the user. |
| UnexpectedFailure UnexpectedFailure | An unexpected error thrown because something went wrong on a lower layer. |
Instances
Constructors
| forall blk.(Typeable blk, StandardHash blk) => 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 |
| forall blk.(Typeable blk, StandardHash blk) => 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. |
throwApiMisuse :: (MonadThrow m, HasCallStack) => ApiMisuse -> m a Source #
data UnexpectedFailure 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. |
| forall blk.(Typeable blk, StandardHash blk) => ChecksumMismatchError (RealPoint blk) CRC CRC FsPath PrettyCallStack | There was a checksum mismatch when reading the block with the given
point. The first |
| forall blk.(Typeable blk, StandardHash blk) => ParseError FsPath (RealPoint blk) DeserialiseFailure | A block failed to parse |
| forall blk.(Typeable blk, StandardHash blk) => TrailingDataError FsPath (RealPoint blk) ByteString | When parsing a block we got some trailing data |
| forall blk.(Typeable blk, StandardHash blk) => 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. |
| forall blk.(Typeable blk, StandardHash blk) => 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
| Show UnexpectedFailure Source # | |
Defined in Ouroboros.Consensus.Storage.ImmutableDB.API Methods showsPrec :: Int -> UnexpectedFailure -> ShowS # show :: UnexpectedFailure -> String # showList :: [UnexpectedFailure] -> ShowS # | |
throwUnexpectedFailure :: MonadThrow m => UnexpectedFailure -> m a Source #
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 (RealPoint blk) | There is no block in the slot of the given point. |
| WrongHash (RealPoint blk) (NonEmpty (HeaderHash blk)) | The block and/or EBB in the slot of the given point have a different hash. |
| 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
missingBlockPoint :: MissingBlock blk -> RealPoint blk Source #
Return the RealPoint of the block that was missing.
Wrappers that preserve HasCallStack
closeDB :: HasCallStack => ImmutableDB m blk -> m () Source #
getTip :: HasCallStack => ImmutableDB m blk -> STM m (WithOrigin (Tip blk)) Source #
getBlockComponent :: HasCallStack => ImmutableDB m blk -> BlockComponent blk b -> RealPoint blk -> m (Either (MissingBlock blk) b) Source #
appendBlock :: HasCallStack => ImmutableDB m blk -> blk -> m () 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
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.
getKnownBlockComponent :: (MonadThrow m, HasHeader blk) => ImmutableDB m blk -> BlockComponent blk b -> RealPoint blk -> m b 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 #
hasBlock :: (MonadSTM m, HasCallStack) => ImmutableDB m blk -> RealPoint blk -> m Bool Source #
getTipPoint :: (MonadSTM m, HasCallStack) => ImmutableDB m blk -> STM m (Point blk) Source #
getTipAnchor :: (MonadSTM m, HasCallStack) => ImmutableDB m blk -> STM m (Anchor blk) Source #
getTipSlot :: (MonadSTM m, HasCallStack) => ImmutableDB m blk -> STM m (WithOrigin SlotNo) Source #