liftIO package:effectful-core

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

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.

Create a local unlifting function with the given strategy along with an unrestricted lifting function. Useful for lifting complicated IO computations where the monadic action shows in both positive (as a result) and negative (as an argument) position. Note: depending on the computation you're lifting localUnliftIO along with withLiftMapIO might be enough and is more efficient.

Create a local unlifting function with the SeqUnlift strategy. For the general version see localUnliftIO.

Create a local unlifting function with the given strategy.

Create an unlifting function with the ConcUnlift strategy.

Create an unlifting function with the SeqUnlift strategy.

Create an unlifting function with the ConcUnlift strategy. This function is unsafe because it can be used to introduce arbitrary IO actions into pure Eff computations.

Create an unlifting function with the SeqUnlift strategy. This function is unsafe because it can be used to introduce arbitrary IO actions into pure Eff computations.

Create an unlifting function. This function is really unsafe because:

• It can be used to introduce arbitrary IO actions into pure Eff computations.
• Unlifted Eff computations must be run in a way that's perceived as sequential to the outside observer, e.g. in the same thread as the caller of reallyUnsafeUnliftIO or in a worker thread that finishes before another unlifted computation is run.

Warning: if you disregard the second point, you will experience weird bugs, data races or internal consistency check failures. When in doubt, use unsafeSeqUnliftIO, especially since this version saves only a simple safety check per call of the unlifting function.

Create an unlifting function with the SeqForkUnlift strategy.