HORIZON HASKELLDocslts/ghc-9.10.xc74966e2026-09-27Search names, modules, packages, or :: a typeCtrl K

GHC 9.10.3 · lts/ghc-9.10.x · c74966e · 2026-09-27

Moduleunliftio-0.2.25.1Haskell2010

UnliftIO

Please see the README.md file for information on using this package at https://www.stackage.org/package/unliftio.

  • 1 type
  • 2 classes
  • 6 values
newtypenewtype UnliftIO (m :: Type -> Type)
#

The ability to run any monadic action m a as IO a.

This is more precisely a natural transformation. We need to new datatype (instead of simply using a forall) due to lack of support in GHC for impredicative types.

Constructors

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

Monads in which IO computations may be embedded. Any monad built by applying a sequence of monad transformers to the IO monad will be an instance of this class.

Instances should satisfy the following laws, which state that liftIO is a transformer of monads:

Methods

  • liftIO :: IO a -> m a

    Lift a computation from the IO monad. This allows us to run IO computations in any monadic stack, so long as it supports these kinds of operations (i.e. IO is the base monad for the stack).

    Example
    import Control.Monad.Trans.State -- from the "transformers" library

printState :: Show s => StateT s IO ()
printState = do
  state <- get
  liftIO $ print state

    Had we omitted liftIO, we would have ended up with this error:

    • Couldn't match type ‘IO’ with ‘StateT s IO’
 Expected type: StateT s IO ()
   Actual type: IO ()

    The important part here is the mismatch between StateT s IO () and IO ().

    Luckily, we know of a function that takes an IO a and returns an (m a): liftIO, enabling us to run the program and see the expected results:

    > evalStateT printState "hello"
"hello"

> evalStateT printState 3
3
Instances18MonadIO, …
classclass MonadIO m => MonadUnliftIO (m :: Type -> Type) where
#

Monads which allow their actions to be run in IO.

While MonadIO allows an IO action to be lifted into another monad, this class captures the opposite concept: allowing you to capture the monadic context. Note that, in order to meet the laws given below, the intuition is that a monad must have no monadic state, but may have monadic context. This essentially limits MonadUnliftIO to ReaderT and IdentityT transformers on top of IO.

Laws. For any function run provided by withRunInIO, it must meet the monad transformer laws as reformulated for MonadUnliftIO:

  • run . return = return
  • run (m >>= f) = run m >>= run . f

Instances of MonadUnliftIO must also satisfy the following laws:

Identity law

withRunInIO (\run -> run m) = m

Inverse law

withRunInIO (\_ -> m) = liftIO m

As an example of an invalid instance, a naive implementation of MonadUnliftIO (StateT s m) might be

withRunInIO inner =
  StateT $ \s ->
    withRunInIO $ \run ->
      inner (run . flip evalStateT s)

This breaks the identity law because the inner run m would throw away any state changes in m.

Methods

  • withRunInIO :: ((forall a. m a -> IO a) -> IO b) -> m b

    Convenience function for capturing the monadic context and running an IO action with a runner function. The runner function is used to run a monadic action m in IO.

Instances3MonadUnliftIO
valueaskRunInIO :: MonadUnliftIO m => m (m a -> IO a)
#

Same as askUnliftIO, but returns a monomorphic function instead of a polymorphic newtype wrapper. If you only need to apply the transformation on one concrete type, this function can be more convenient.

valueliftIOOp :: MonadUnliftIO m => (IO a -> IO b) -> m a -> m b
#

A helper function for lifting IO a -> IO b functions into any MonadUnliftIO.

Example
liftedTry :: (Exception e, MonadUnliftIO m) => m a -> m (Either e a)
liftedTry m = liftIOOp Control.Exception.try m
valuewrappedWithRunInIO
  1. :: MonadUnliftIO n
  2. => (n b -> m b)

    The wrapper, for instance IdentityT.

  3. -> (forall a. m a -> n a)

    The inverse, for instance runIdentityT.

  4. -> ((forall a. m a -> IO a) -> IO b)

    The actual function to invoke withRunInIO with.

  5. -> m b
#

A helper function for implementing MonadUnliftIO instances. Useful for the common case where you want to simply delegate to the underlying transformer.

Note: You can derive MonadUnliftIO for newtypes without this helper function in unliftio-core 0.2.0.0 and later.

Example
newtype AppT m a = AppT { unAppT :: ReaderT Int (ResourceT m) a }
  deriving (Functor, Applicative, Monad, MonadIO)

-- Same as `deriving newtype (MonadUnliftIO)`
instance MonadUnliftIO m => MonadUnliftIO (AppT m) where
  withRunInIO = wrappedWithRunInIO AppT unAppT

module UnliftIO.Async

module UnliftIO.Chan

module UnliftIO.Exception

module UnliftIO.IO

module UnliftIO.IORef

module UnliftIO.Memoize

module UnliftIO.MVar

module UnliftIO.QSem

module UnliftIO.QSemN

module UnliftIO.STM

module UnliftIO.Temporary

module UnliftIO.Timeout