Safe Haskell	None
Language	Haskell2010

Ouroboros.Consensus.Storage.ImmutableDB.API

Contents

API
Iterator API
Types
Errors
Wrappers that preserve HasCallStack
Derived functionality

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
- = IteratorExhausted
- | 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
}
data Tip blk = Tip {
- tipSlotNo :: ! SlotNo
- tipIsEBB :: ! IsEBB
- tipBlockNo :: ! BlockNo
- tipHash :: !( HeaderHash blk)
}
blockToTip :: ( HasHeader blk, GetHeader blk) => 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)
- | 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 SlotNo s. 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 Iterator s, 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

closeDB_ :: HasCallStack => m ()

Close the database.

Idempotent.

Note : Use withDB instead of this function.
getTip_ :: HasCallStack => STM m ( WithOrigin ( Tip blk))

Return the tip of the database.

The tip of the database will never point to an unfilled slot or missing EBB.

Throws a ClosedDBError if the database is closed.
getBlockComponent_ :: forall b. HasCallStack => BlockComponent blk b -> RealPoint blk -> m ( Either ( MissingBlock blk) b)

Get the block component of the block with the given Point .

The hash of the point is used to distinguish a potential EBB from the regular block in the same slot.

Returns a MissingBlockError if no block was stored with the given Point , either because the slot was empty or because the block stored with that slot had a different hash.

Throws a ClosedDBError if the database is closed.
appendBlock_ :: HasCallStack => blk -> m ()

Appends a block to the ImmutableDB.

Throws an AppendBlockNotNewerThanTipError if the given slot is <= the result of getTip .

Throws a ClosedDBError if the database is closed.
stream_ :: forall b. HasCallStack => ResourceRegistry m -> BlockComponent blk b -> StreamFrom blk -> StreamTo blk -> m ( Either ( MissingBlock blk) ( Iterator m blk b))

Return an Iterator to efficiently stream blocks from the ImmutableDB.

Throws an InvalidIteratorRangeError if the start of the range is greater than the end of the range.

NOTE: MissingBlock is returned, but InvalidIteratorRangeError is thrown. This is because the former is expected to occur during normal operation: a node serving blocks might get requests to stream blocks that are not in the database. The latter exception indicates incorrect usage and should not happen during normal operation.

Throws a ClosedDBError if the database is closed.

The iterator is automatically closed when exhausted, and can be prematurely closed with iteratorClose .

Instances

Instances details

NoThunks ( ImmutableDB m blk) Source #
Instance details Defined in Ouroboros.Consensus.Storage.ImmutableDB.API Methods noThunks :: Context -> ImmutableDB m blk -> IO ( Maybe ThunkInfo ) Source # wNoThunks :: Context -> ImmutableDB m blk -> IO ( Maybe ThunkInfo ) Source # showTypeOf :: Proxy ( ImmutableDB m blk) -> String Source #

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

iteratorNext :: HasCallStack => m ( IteratorResult b)

Steps an Iterator yielding an IteratorResult .

After returning the block component as an IteratorResult , the iterator is advanced to the next non-empty slot or non-empty EBB.

Throws a ClosedDBError if the database is closed.

The iterator is automatically closed when exhausted ( IteratorExhausted ), and can be prematurely closed with iteratorClose .
iteratorHasNext :: HasCallStack => STM m ( Maybe ( RealPoint blk))

Return the point of the next block to stream, if there is one. Return Nothing if not.

This operation is idempotent.
iteratorClose :: HasCallStack => m ()

Dispose of the Iterator by closing any open handles.

Idempotent operation.

Instances

Instances details

Functor m => Functor ( Iterator m blk) Source #
Instance details Defined in Ouroboros.Consensus.Storage.ImmutableDB.API Methods fmap :: (a -> b) -> Iterator m blk a -> Iterator m blk b Source # (<$) :: a -> Iterator m blk b -> Iterator m blk a Source #
NoThunks ( Iterator m blk b) Source #
Instance details Defined in Ouroboros.Consensus.Storage.ImmutableDB.API Methods noThunks :: Context -> Iterator m blk b -> IO ( Maybe ThunkInfo ) Source # wNoThunks :: Context -> Iterator m blk b -> IO ( Maybe ThunkInfo ) Source # showTypeOf :: Proxy ( Iterator m blk b) -> String Source #

data IteratorResult b Source #

The result of stepping an Iterator .

Constructors

IteratorExhausted
IteratorResult b

Instances

Instances details

Functor IteratorResult Source #
Instance details Defined in Ouroboros.Consensus.Storage.ImmutableDB.API Methods fmap :: (a -> b) -> IteratorResult a -> IteratorResult b Source # (<$) :: a -> IteratorResult b -> IteratorResult a Source #
Foldable IteratorResult Source #
Instance details Defined in Ouroboros.Consensus.Storage.ImmutableDB.API Methods fold :: Monoid m => IteratorResult m -> m Source # foldMap :: Monoid m => (a -> m) -> IteratorResult a -> m Source # foldMap' :: Monoid m => (a -> m) -> IteratorResult a -> m Source # foldr :: (a -> b -> b) -> b -> IteratorResult a -> b Source # foldr' :: (a -> b -> b) -> b -> IteratorResult a -> b Source # foldl :: (b -> a -> b) -> b -> IteratorResult a -> b Source # foldl' :: (b -> a -> b) -> b -> IteratorResult a -> b Source # foldr1 :: (a -> a -> a) -> IteratorResult a -> a Source # foldl1 :: (a -> a -> a) -> IteratorResult a -> a Source # toList :: IteratorResult a -> [a] Source # null :: IteratorResult a -> Bool Source # length :: IteratorResult a -> Int Source # elem :: Eq a => a -> IteratorResult a -> Bool Source # maximum :: Ord a => IteratorResult a -> a Source # minimum :: Ord a => IteratorResult a -> a Source # sum :: Num a => IteratorResult a -> a Source # product :: Num a => IteratorResult a -> a Source #
Traversable IteratorResult Source #
Instance details Defined in Ouroboros.Consensus.Storage.ImmutableDB.API Methods traverse :: Applicative f => (a -> f b) -> IteratorResult a -> f ( IteratorResult b) Source # sequenceA :: Applicative f => IteratorResult (f a) -> f ( IteratorResult a) Source # mapM :: Monad m => (a -> m b) -> IteratorResult a -> m ( IteratorResult b) Source # sequence :: Monad m => IteratorResult (m a) -> m ( IteratorResult a) Source #
Eq b => Eq ( IteratorResult b) Source #
Instance details Defined in Ouroboros.Consensus.Storage.ImmutableDB.API Methods (==) :: IteratorResult b -> IteratorResult b -> Bool Source # (/=) :: IteratorResult b -> IteratorResult b -> Bool Source #
Show b => Show ( IteratorResult b) Source #
Instance details Defined in Ouroboros.Consensus.Storage.ImmutableDB.API Methods showsPrec :: Int -> IteratorResult b -> ShowS Source # show :: IteratorResult b -> String Source # showList :: [ IteratorResult b] -> ShowS Source #
Generic ( IteratorResult b) Source #
Instance details Defined in Ouroboros.Consensus.Storage.ImmutableDB.API Associated Types type Rep ( IteratorResult b) :: Type -> Type Source # Methods from :: IteratorResult b -> Rep ( IteratorResult b) x Source # to :: Rep ( IteratorResult b) x -> IteratorResult b Source #
type Rep ( IteratorResult b) Source #
Instance details Defined in Ouroboros.Consensus.Storage.ImmutableDB.API type Rep ( IteratorResult b) = D1 (' MetaData "IteratorResult" "Ouroboros.Consensus.Storage.ImmutableDB.API" "ouroboros-consensus-0.1.0.1-DT4Cvwf63DZKctsEvaJqCU" ' False ) ( C1 (' MetaCons "IteratorExhausted" ' PrefixI ' False ) ( U1 :: Type -> Type ) :+: C1 (' MetaCons "IteratorResult" ' PrefixI ' False ) ( S1 (' MetaSel (' Nothing :: Maybe Symbol ) ' NoSourceUnpackedness ' NoSourceStrictness ' DecidedLazy ) ( Rec0 b)))

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 IteratorResult s (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 m that executes the monadic function when calling iteratorNext .

Types

newtype CompareTip blk Source #

newtype with an Ord instance that only uses tipSlotNo and tipIsEBB and ignores the other fields.

Constructors

CompareTip
Fields getCompareTip :: Tip blk

Instances

Instances details

Eq ( CompareTip blk) Source #
Instance details Defined in Ouroboros.Consensus.Storage.ImmutableDB.API Methods (==) :: CompareTip blk -> CompareTip blk -> Bool Source # (/=) :: CompareTip blk -> CompareTip blk -> Bool Source #
Ord ( CompareTip blk) Source #
Instance details Defined in Ouroboros.Consensus.Storage.ImmutableDB.API Methods compare :: CompareTip blk -> CompareTip blk -> Ordering Source # (<) :: CompareTip blk -> CompareTip blk -> Bool Source # (<=) :: CompareTip blk -> CompareTip blk -> Bool Source # (>) :: CompareTip blk -> CompareTip blk -> Bool Source # (>=) :: CompareTip blk -> CompareTip blk -> Bool Source # max :: CompareTip blk -> CompareTip blk -> CompareTip blk Source # min :: CompareTip blk -> CompareTip blk -> CompareTip blk Source #

data Tip blk Source #

Information about the tip of the ImmutableDB.

Constructors

Tip
Fields tipSlotNo :: ! SlotNo tipIsEBB :: ! IsEBB tipBlockNo :: ! BlockNo tipHash :: !( HeaderHash blk)

Instances

Instances details

StandardHash blk => Eq ( Tip blk) Source #
Instance details Defined in Ouroboros.Consensus.Storage.ImmutableDB.API Methods (==) :: Tip blk -> Tip blk -> Bool Source # (/=) :: Tip blk -> Tip blk -> Bool Source #
StandardHash blk => Show ( Tip blk) Source #
Instance details Defined in Ouroboros.Consensus.Storage.ImmutableDB.API Methods showsPrec :: Int -> Tip blk -> ShowS Source # show :: Tip blk -> String Source # showList :: [ Tip blk] -> ShowS Source #
Generic ( Tip blk) Source #
Instance details Defined in Ouroboros.Consensus.Storage.ImmutableDB.API Associated Types type Rep ( Tip blk) :: Type -> Type Source # Methods from :: Tip blk -> Rep ( Tip blk) x Source # to :: Rep ( Tip blk) x -> Tip blk Source #
StandardHash blk => NoThunks ( Tip blk) Source #
Instance details Defined in Ouroboros.Consensus.Storage.ImmutableDB.API Methods noThunks :: Context -> Tip blk -> IO ( Maybe ThunkInfo ) Source # wNoThunks :: Context -> Tip blk -> IO ( Maybe ThunkInfo ) Source # showTypeOf :: Proxy ( Tip blk) -> String Source #
type Rep ( Tip blk) Source #
Instance details Defined in Ouroboros.Consensus.Storage.ImmutableDB.API type Rep ( Tip blk) = D1 (' MetaData "Tip" "Ouroboros.Consensus.Storage.ImmutableDB.API" "ouroboros-consensus-0.1.0.1-DT4Cvwf63DZKctsEvaJqCU" ' 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 :: ( HasHeader blk, 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

data ApiMisuse blk Source #

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 `RealPoint` corresponds to the new block and the `Point` to the current tip.
InvalidIteratorRangeError ( StreamFrom blk) ( StreamTo blk)	When the chosen iterator range was invalid, i.e. the `start` (first parameter) came after the `end` (second parameter).
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.

Instances

Instances details

( StandardHash blk, Typeable blk) => Show ( ApiMisuse blk) Source #
Instance details Defined in Ouroboros.Consensus.Storage.ImmutableDB.API Methods showsPrec :: Int -> ApiMisuse blk -> ShowS Source # show :: ApiMisuse blk -> String Source # showList :: [ ApiMisuse blk] -> ShowS Source #

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

Instances details

( StandardHash blk, Typeable blk) => Show ( ImmutableDBError blk) Source #
Instance details Defined in Ouroboros.Consensus.Storage.ImmutableDB.API Methods showsPrec :: Int -> ImmutableDBError blk -> ShowS Source # show :: ImmutableDBError blk -> String Source # showList :: [ ImmutableDBError blk] -> ShowS Source #
Generic ( ImmutableDBError blk) Source #
Instance details Defined in Ouroboros.Consensus.Storage.ImmutableDB.API Associated Types type Rep ( ImmutableDBError blk) :: Type -> Type Source # Methods from :: ImmutableDBError blk -> Rep ( ImmutableDBError blk) x Source # to :: Rep ( ImmutableDBError blk) x -> ImmutableDBError blk Source #
( StandardHash blk, Typeable blk) => Exception ( ImmutableDBError blk) Source #
Instance details Defined in Ouroboros.Consensus.Storage.ImmutableDB.API Methods toException :: ImmutableDBError blk -> SomeException Source # fromException :: SomeException -> Maybe ( ImmutableDBError blk) Source # displayException :: ImmutableDBError blk -> String Source #
type Rep ( ImmutableDBError blk) Source #
Instance details Defined in Ouroboros.Consensus.Storage.ImmutableDB.API type Rep ( ImmutableDBError blk) = D1 (' MetaData "ImmutableDBError" "Ouroboros.Consensus.Storage.ImmutableDB.API" "ouroboros-consensus-0.1.0.1-DT4Cvwf63DZKctsEvaJqCU" ' False ) ( C1 (' MetaCons "ApiMisuse" ' PrefixI ' False ) ( S1 (' MetaSel (' Nothing :: Maybe Symbol ) ' NoSourceUnpackedness ' NoSourceStrictness ' DecidedLazy ) ( Rec0 ( ApiMisuse blk)) :*: S1 (' MetaSel (' Nothing :: Maybe Symbol ) ' NoSourceUnpackedness ' NoSourceStrictness ' DecidedLazy ) ( Rec0 PrettyCallStack )) :+: C1 (' MetaCons "UnexpectedFailure" ' PrefixI ' False ) ( S1 (' MetaSel (' Nothing :: Maybe Symbol ) ' NoSourceUnpackedness ' NoSourceStrictness ' DecidedLazy ) ( Rec0 ( UnexpectedFailure blk))))

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

Instances details

StandardHash blk => Eq ( MissingBlock blk) Source #
Instance details Defined in Ouroboros.Consensus.Storage.ImmutableDB.API Methods (==) :: MissingBlock blk -> MissingBlock blk -> Bool Source # (/=) :: MissingBlock blk -> MissingBlock blk -> Bool Source #
StandardHash blk => Show ( MissingBlock blk) Source #
Instance details Defined in Ouroboros.Consensus.Storage.ImmutableDB.API Methods showsPrec :: Int -> MissingBlock blk -> ShowS Source # show :: MissingBlock blk -> String Source # showList :: [ MissingBlock blk] -> ShowS Source #
Generic ( MissingBlock blk) Source #
Instance details Defined in Ouroboros.Consensus.Storage.ImmutableDB.API Associated Types type Rep ( MissingBlock blk) :: Type -> Type Source # Methods from :: MissingBlock blk -> Rep ( MissingBlock blk) x Source # to :: Rep ( MissingBlock blk) x -> MissingBlock blk Source #
type Rep ( MissingBlock blk) Source #
Instance details Defined in Ouroboros.Consensus.Storage.ImmutableDB.API type Rep ( MissingBlock blk) = D1 (' MetaData "MissingBlock" "Ouroboros.Consensus.Storage.ImmutableDB.API" "ouroboros-consensus-0.1.0.1-DT4Cvwf63DZKctsEvaJqCU" ' False ) ( C1 (' MetaCons "EmptySlot" ' PrefixI ' False ) ( S1 (' MetaSel (' Nothing :: Maybe Symbol ) ' NoSourceUnpackedness ' NoSourceStrictness ' DecidedLazy ) ( Rec0 ( RealPoint blk))) :+: ( C1 (' MetaCons "WrongHash" ' PrefixI ' False ) ( S1 (' MetaSel (' Nothing :: Maybe Symbol ) ' NoSourceUnpackedness ' NoSourceStrictness ' DecidedLazy ) ( Rec0 ( RealPoint blk)) :: S1 (' MetaSel (' Nothing :: Maybe Symbol ) ' NoSourceUnpackedness ' NoSourceStrictness ' DecidedLazy ) ( Rec0 ( NonEmpty ( HeaderHash blk)))) :+: C1 (' MetaCons "NewerThanTip" ' PrefixI ' False ) ( S1 (' MetaSel (' Nothing :: Maybe Symbol ) ' NoSourceUnpackedness ' NoSourceStrictness ' DecidedLazy ) ( Rec0 ( RealPoint blk)) :: S1 (' MetaSel (' Nothing :: Maybe Symbol ) ' NoSourceUnpackedness ' NoSourceStrictness ' DecidedLazy ) ( Rec0 ( Point blk)))))

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 `CRC` is the expected one, the second one the actual one.
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 `GetVerifiedBlock` . 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

Instances details

( StandardHash blk, Typeable blk) => Show ( UnexpectedFailure blk) Source #
Instance details Defined in Ouroboros.Consensus.Storage.ImmutableDB.API Methods showsPrec :: Int -> UnexpectedFailure blk -> ShowS Source # show :: UnexpectedFailure blk -> String Source # showList :: [ UnexpectedFailure blk] -> ShowS Source #

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 #

withDB 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.

API

Instances

Iterator API

Instances

Instances

Types

Instances

Instances

Errors

Instances

Instances

Instances

Instances

Wrappers that preserve HasCallStack

Derived functionality

Wrappers that preserve `HasCallStack`