Documentation

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 .

Since: 0.1.0.0

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.

Since: 0.1.0.0

Capture the current monadic context, providing the ability to run monadic actions in IO .

See UnliftIO for an explanation of why we need a helper datatype here.

Prior to version 0.2.0.0 of this library, this was a method in the MonadUnliftIO type class. It was moved out due to https://github.com/fpco/unliftio/issues/55 .

Since: 0.1.0.0

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.

Since: 0.1.0.0

Convenience function for capturing the monadic context and running an IO action. The UnliftIO newtype wrapper is rarely needed, so prefer withRunInIO to this function.

Since: 0.1.0.0

Convert an action in m to an action in IO .

Since: 0.1.0.0

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

Since: 0.1.2.0

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

Since: 0.2.1.0

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:

• liftIO . return = return

• liftIO (m >>= f) = liftIO m >>= (liftIO . f)