HORIZON HASKELLDocslts/ghc-9.14.xd82dee82026-10-12Search names, modules, packages, or :: a typeCtrl K

GHC 9.14.1 · lts/ghc-9.14.x · d82dee8 · 2026-10-12

Moduleouroboros-consensus-4.2.1.0

Ouroboros.Consensus.Util.IOLike

  • 13 types
  • 20 classes
  • 87 values
valuecheckInvariant :: HasCallStack => Maybe String -> a -> a
#

Check invariant (if enabled) before continuing

checkInvariant mErr x is equal to x if mErr == Nothing, and throws an error err if mErr == Just err.

This is exported so that other code that wants to conditionally check invariants can reuse the same logic, rather than having to introduce new per-package flags.

valuetoLazyMVar :: StrictMVar m a -> LazyMVar m a
#

Get the underlying MVar

Since we obviously can not guarantee that updates to this LazyMVar will be strict, this should be used with caution.

Similarly, we can not guarantee that updates to this LazyMVar do not break the original invariant that the StrictMVar held.

valueunsafeToUncheckedStrictMVar :: StrictMVar m a -> StrictMVar m a
#

Create an unchecked reference to the given checked StrictMVar.

Note that the invariant is only guaranteed when modifying the checked MVar. Any modification to the unchecked reference might break the invariants.

valuefromLazyTVar :: LazyTVar m a -> StrictTVar m a
#

Create a StrictMVar from a LazyMVar

It is not guaranteed that the LazyTVar contains a value that is in WHNF, so there is no guarantee that the resulting StrictTVar contains a value that is in WHNF. This should be used with caution.

The resulting StrictTVar has a trivial invariant.

valuetoLazyTVar :: StrictTVar m a -> LazyTVar m a
#

Get the underlying TVar

Since we obviously cannot guarantee that updates to this LazyTVar will be strict, this should be used with caution.

Similarly, we can not guarantee that updates to this LazyTVar do not break the original invariant that the StrictTVar held.

valueunsafeToUncheckedStrictTVar :: StrictTVar m a -> StrictTVar m a
#

Create an unchecked reference to the given checked StrictTVar.

Note that the invariant is only guaranteed when modifying the checked TVar. Any modification to the unchecked reference might break the invariants.

classclass (Typeable e, Show e) => Exception e where
#

Any type that you wish to throw or catch as an exception must be an instance of the Exception class. The simplest case is a new exception type directly below the root:

data MyException = ThisException | ThatException
    deriving Show

instance Exception MyException

The default method definitions in the Exception class do what we need in this case. You can now throw and catch ThisException and ThatException as exceptions:

*Main> throw ThisException `catch` \e -> putStrLn ("Caught " ++ show (e :: MyException))
Caught ThisException

In more complicated examples, you may wish to define a whole hierarchy of exceptions:

---------------------------------------------------------------------
-- Make the root exception type for all the exceptions in a compiler

data SomeCompilerException = forall e . Exception e => SomeCompilerException e

instance Show SomeCompilerException where
    show (SomeCompilerException e) = show e

instance Exception SomeCompilerException

compilerExceptionToException :: Exception e => e -> SomeException
compilerExceptionToException = toException . SomeCompilerException

compilerExceptionFromException :: Exception e => SomeException -> Maybe e
compilerExceptionFromException x = do
    SomeCompilerException a <- fromException x
    cast a

---------------------------------------------------------------------
-- Make a subhierarchy for exceptions in the frontend of the compiler

data SomeFrontendException = forall e . Exception e => SomeFrontendException e

instance Show SomeFrontendException where
    show (SomeFrontendException e) = show e

instance Exception SomeFrontendException where
    toException = compilerExceptionToException
    fromException = compilerExceptionFromException

frontendExceptionToException :: Exception e => e -> SomeException
frontendExceptionToException = toException . SomeFrontendException

frontendExceptionFromException :: Exception e => SomeException -> Maybe e
frontendExceptionFromException x = do
    SomeFrontendException a <- fromException x
    cast a

---------------------------------------------------------------------
-- Make an exception type for a particular frontend compiler exception

data MismatchedParentheses = MismatchedParentheses
    deriving Show

instance Exception MismatchedParentheses where
    toException   = frontendExceptionToException
    fromException = frontendExceptionFromException

We can now catch a MismatchedParentheses exception as MismatchedParentheses, SomeFrontendException or SomeCompilerException, but not other types, e.g. IOException:

*Main> throw MismatchedParentheses `catch` \e -> putStrLn ("Caught " ++ show (e :: MismatchedParentheses))
Caught MismatchedParentheses
*Main> throw MismatchedParentheses `catch` \e -> putStrLn ("Caught " ++ show (e :: SomeFrontendException))
Caught MismatchedParentheses
*Main> throw MismatchedParentheses `catch` \e -> putStrLn ("Caught " ++ show (e :: SomeCompilerException))
Caught MismatchedParentheses
*Main> throw MismatchedParentheses `catch` \e -> putStrLn ("Caught " ++ show (e :: IOException))
*** Exception: MismatchedParentheses

Methods

Instances139Exception, …
datadata SomeException
#

The SomeException type is the root of the exception type hierarchy. When an exception of type e is thrown, behind the scenes it is encapsulated in a SomeException.

Instances26Show, Exception, AsAllocationLimitExceeded, AsArithException, AsArrayException, AsAssertionFailed, …
classclass (MonadSTM m, MonadThread m) => MonadAsync (m :: Type -> Type) where
#

Associated types

Methods

Instances3MonadAsync
classclass MonadThread m => MonadFork (m :: Type -> Type) where
#

Methods

Instances3MonadFork
classclass (Monad m, Eq (ThreadId m), Ord (ThreadId m), Show (ThreadId m)) => MonadThread (m :: Type -> Type) where
#

Associated types

Methods

Instances3MonadThread
classclass PrimMonad m => MonadST (m :: Type -> Type) where
#

Methods

Instances4MonadST
classclass (MonadSTM m, Monad (InspectMonadSTM m)) => MonadInspectSTM (m :: Type -> Type) where
#

Associated types

Methods

Instances3MonadInspectSTM
classclass MonadSTM m => MonadLabelledSTM (m :: Type -> Type) where
#

Methods

Instances2MonadLabelledSTM
classclass (Monad m, Monad (STM m)) => MonadSTM (m :: Type -> Type) where
#

Associated types

Methods

Instances3MonadSTM
classclass MonadInspectSTM m => MonadTraceSTM (m :: Type -> Type) where
#

Methods

Instances3MonadTraceSTM
familytype family STM (m :: Type -> Type) :: Type -> Type
#
Instances3STM
  • type STM IO = STMDefined in io-classes-1.8.0.1 · Control.Monad.Class.MonadSTM.Internal
  • type STM (WithEarlyExit m) = WithEarlyExit (STM m)Defined in ouroboros-consensus-4.2.1.0 · Ouroboros.Consensus.Util.EarlyExit
  • type STM (ReaderT r m) = ReaderT r (STM m)Defined in io-classes-1.8.0.1 · Control.Monad.Class.MonadSTM.Internal
classclass MonadThrow m => MonadCatch (m :: Type -> Type) where
#

Methods

Instances6MonadCatch
classclass MonadCatch m => MonadMask (m :: Type -> Type) where
#

Methods

Instances4MonadMask
classclass Monad m => MonadThrow (m :: Type -> Type) where
#

Methods

Instances6MonadThrow
newtypenewtype Time
#

Constructors

Instances1Condense
  • Condense TimeDefined in ouroboros-consensus-4.2.1.0 · Ouroboros.Consensus.Util.Condense
classclass NoThunks a where
#

Check a value for unexpected thunks

Methods

  • noThunks :: Context -> a -> IO (Maybe ThunkInfo)

    Check if the argument does not contain any unexpected thunks

    For most datatypes, we should have that

    noThunks ctxt x == Nothing

    if and only if

    checkContainsThunks x

    For some datatypes however, some thunks are expected. For example, the internal fingertree Data.Sequence.Sequence might contain thunks (this is important for the asymptotic complexity of this data structure). However, we should still check that the values in the sequence don't contain any unexpected thunks.

    This means that we need to traverse the sequence, which might force some of the thunks in the tree. In general, it is acceptable for noThunks to force such "expected thunks", as long as it always reports the unexpected thunks.

    The default implementation of noThunks checks that the argument is in WHNF, and if so, adds the type into the context (using showTypeOf or whereFrom if available), and calls wNoThunks. See ThunkInfo for a detailed discussion of the type context.

    See also discussion of caveats listed for checkContainsThunks.

  • wNoThunks :: Context -> a -> IO (Maybe ThunkInfo)

    Check that the argument is in normal form, assuming it is in WHNF.

    The context will already have been extended with the type we're looking at, so all that's left is to look at the thunks inside the type. The default implementation uses GHC Generics to do this.

  • showTypeOf :: Proxy a -> String

    Show type a (to add to the context)

    We try hard to avoid Typeable constraints in this module: there are types with no Typeable instance but with a NoThunks instance (most important example are types such as ST s which rely on parametric polymorphism). By default we should therefore only show the "outer layer"; for example, if we have a type

    Seq (ST s ())

    then showTypeOf should just give Seq, leaving it up to the instance for ST to decide how to implement showTypeOf; this keeps things compositional. The default implementation does precisely this using the metadata that GHC Generics provides.

    For convenience, however, some of the deriving via newtype wrappers we provide do depend on Typeable; see below.

Instances727NoThunks, …
classclass (MonadAsync m, MonadLabelledSTM m, MonadTraceSTM m, MonadMVar m, MonadEventlog m, MonadFork m, MonadST m, MonadDelay m, MonadThread m, MonadThrow m, MonadCatch m, MonadMask m, MonadMonotonicTime m, MonadEvaluate m, MonadTraceSTM m, Alternative (STM m), MonadCatch (STM m), PrimMonad m, MonadLabelledSTM m, forall a. NoThunks (m a), forall a. NoThunks a => NoThunks (StrictTVar m a), forall a. NoThunks a => NoThunks (StrictSVar m a), forall a. NoThunks a => NoThunks (StrictMVar m a), forall a. NoThunks a => NoThunks (StrictTVar m a), forall a. NoThunks a => NoThunks (StrictMVar m a), forall a. NoThunks a => NoThunks (StrictTMVar m a)) => IOLike (m :: Type -> Type) where
#

Methods

Instances2IOLike
classclass Monad m => PrimMonad (m :: Type -> Type) where
#

Class of monads which can perform primitive state-transformer actions.

Associated types

Methods

Instances27PrimMonad, …
newtypenewtype StrictMVar (m :: Type -> Type) a
#

A strict MVar with invariant checking.

There is a weaker invariant for a StrictMVar than for a StrictTVar: although all functions that modify the StrictMVar check the invariant, we do not guarantee that the value inside the StrictMVar always satisfies the invariant. Instead, we do guarantee that if the StrictMVar is updated with a value that does not satisfy the invariant, an exception is thrown. The reason for this weaker guarantee is that leaving an MVar empty can lead to very hard to debug "blocked indefinitely" problems.

Instances1NoThunks
  • NoThunks (StrictMVar IO a) => NoThunks (StrictMVar IO a)Defined in ouroboros-consensus-4.2.1.0 · Ouroboros.Consensus.Util.NormalForm.StrictMVar · orphan
newtypenewtype DiffTime
#

This is a length of time, as measured by a clock. Conversion functions such as fromInteger and realToFrac will treat it as seconds. For example, (0.010 :: DiffTime) corresponds to 10 milliseconds.

It has a precision of one picosecond (= 10^-12 s). Enumeration functions will treat it as picoseconds.

Instances22Enum, Eq, Fractional, Data, Num, Ord, …
  • Enum DiffTimeDefined in time-1.15 · Data.Time.Clock.Internal.DiffTime
  • Eq DiffTimeDefined in time-1.15 · Data.Time.Clock.Internal.DiffTime
  • Fractional DiffTimeDefined in time-1.15 · Data.Time.Clock.Internal.DiffTime
  • Data DiffTimeDefined in time-1.15 · Data.Time.Clock.Internal.DiffTime
  • Num DiffTimeDefined in time-1.15 · Data.Time.Clock.Internal.DiffTime
  • Ord DiffTimeDefined in time-1.15 · Data.Time.Clock.Internal.DiffTime
  • Read DiffTimeDefined in time-1.15 · Data.Time.Clock.Internal.DiffTime
  • Real DiffTimeDefined in time-1.15 · Data.Time.Clock.Internal.DiffTime
  • RealFrac DiffTimeDefined in time-1.15 · Data.Time.Clock.Internal.DiffTime
  • Show DiffTimeDefined in time-1.15 · Data.Time.Clock.Internal.DiffTime
  • NFData DiffTimeDefined in time-1.15 · Data.Time.Clock.Internal.DiffTime
  • FormatTime DiffTimeDefined in time-1.15 · Data.Time.Format.Format.Instances · orphan
  • ParseTime DiffTimeDefined in time-1.15 · Data.Time.Format.Parse.Instances · orphan
  • Arbitrary DiffTimeDefined in quickcheck-instances-0.4 · Test.QuickCheck.Instances.Time · orphan
  • CoArbitrary DiffTimeDefined in quickcheck-instances-0.4 · Test.QuickCheck.Instances.Time · orphan
  • Function DiffTimeDefined in quickcheck-instances-0.4 · Test.QuickCheck.Instances.Time · orphan
  • Hashable DiffTimeDefined in time-compat-1.9.9 · Data.Time.Orphans · orphan
  • FromJSON DiffTimeDefined in aeson-2.2.5.1 · Data.Aeson.Types.FromJSON

    This instance includes a bounds check to prevent maliciously large inputs to fill up the memory of the target system. You can newtype Scientific and provide your own instance using withScientific if you want to allow larger inputs.

  • ToJSON DiffTimeDefined in aeson-2.2.5.1 · Data.Aeson.Types.ToJSON
  • NoThunks DiffTimeDefined in nothunks-0.3.1 · NoThunks.Class
  • Buildable DiffTimeDefined in formatting-7.2.0 · Formatting.Buildable
  • Lift DiffTimeDefined in time-1.15 · Data.Time.Clock.Internal.DiffTime

Orphan instances

3 instances