unliftio

The MonadUnliftIO typeclass solves the problem of running computations that require IO (like withBinaryFile or bracket) inside a monad transformer stack (like ReaderT Env IO) without manually unwrapping constructors or being limited by MonadIO.

While MonadIO allows you to lift IO actions into your monad using liftIO, it cannot handle functions where IO appears in a negative/argument position (e.g., a callback function that expects IO a but you want to provide m a).

MonadUnliftIO provides the withRunInIO method, which allows you to capture a function (runInIO) that can execute any computation from your monad m as if it were in IO. This is the "unlift" operation.

import Control.Monad.IO.Unlift

-- Example: Unlifting a function that takes a callback in IO
myWithBinaryFile
    :: MonadUnliftIO m
    => FilePath
    -> IOMode
    -> (Handle -> m a)
    -> m a
myWithBinaryFile fp mode inner =
  withRunInIO $ \runInIO ->
  withBinaryFile
    fp
    mode
    (\h -> runInIO (inner h))

When deciding whether to use unliftio, consider how it compares to other common Haskell patterns for handling control flow and exceptions in monad transformers:

• vs. exceptions (MonadThrow, MonadCatch, MonadMask): The exceptions package allows modeling both pure (e.g., Either) and side-effecting (IO) monads with one paradigm. unliftio instead encourages using Either for pure functions and runtime exceptions for IO. unliftio replaces MonadMask with MonadUnliftIO to restrict usage to a safer subset of monads.
• vs. monad-control: monad-control uses a MonadBase style, allowing unlifting to arbitrary base monads (like STM). unliftio uses a MonadIO style, which is more common and simpler, but limits unlifting to IO.
• vs. monad-unlift: monad-unlift uses complex type-level features to restrict monad-control to a safe subset. unliftio provides a simpler, more approachable typeclass (MonadUnliftIO) that is easier for GHC to compile and easier for developers to understand.

Key Design Choice: unliftio prioritly avoids the 'state discard' problem found in monad-control (where operations like finally in a StateT transformer might discard mutated state) by disallowing unsafe unlifting at the type level.

To use unliftio in your project, you can follow these patterns to improve safety and simplify your dependency tree:

• Replace Exception Imports: Swap Control.Exception with UnliftIO.Exception. This provides more powerful and safer versions of catch and finally by adjusting asynchronous exception semantics.
• Replace Async Imports: Swap Control.Concurrent.Async with UnliftIO.Async.
• Full Import: Alternatively, you can import UnliftIO to bring in the library's capabilities.
• Resolve Naming Conflicts: If there are conflicts between standard libraries and unliftio, let unliftio win.
• Simplify Dependencies: You can often drop dependencies on monad-control, lifted-base, and exceptions when using unliftio.

Note on Exceptions: UnliftIO.Exception uses semantics similar to the safe-exceptions package. While generally an improvement, it may not be a drop-in replacement for Control.Exception in highly advanced exception-handling code due to how it handles asynchronous exceptions.