Control.Monad.Managed

An example Haskell program to copy data from one handle to another might look like this:

main =
    withFile "inFile.txt" ReadMode $ \inHandle ->
        withFile "outFile.txt" WriteMode $ \outHandle ->
            copy inHandle outHandle

-- A hypothetical function that copies data from one handle to another
copy :: Handle -> Handle -> IO ()

withFile is one of many functions that acquire some resource in an exception-safe way. These functions take a callback function as an argument and they invoke the callback on the resource when it becomes available, guaranteeing that the resource is properly disposed if the callback throws an exception.

These functions usually have a type that ends with the following pattern:

                   Callback
--                -----------
withXXX :: ... -> (a -> IO r) -> IO r

Here are some examples of this pattern from the base libraries:

withArray      :: Storable a => [a] -> (Ptr a   -> IO r) -> IO r
withBuffer     ::          Buffer e -> (Ptr e   -> IO r) -> IO r
withCAString   ::            String -> (CString -> IO r) -> IO r
withForeignPtr ::      ForeignPtr a -> (Ptr a   -> IO r) -> IO r
withMVar       ::            Mvar a -> (a       -> IO r) -> IO r
withPool       ::                      (Pool    -> IO r) -> IO r

Acquiring multiple resources in this way requires nesting callbacks. However, you can wrap anything of the form ((a -> IO r) -> IO r) in the Managed monad, which translates binds to callbacks for you:

import Control.Monad.Managed
import System.IO

inFile :: FilePath -> Managed Handle
inFile filePath = managed (withFile filePath ReadMode)

outFile :: FilePath -> Managed Handle
outFile filePath = managed (withFile filePath WriteMode)

main = runManaged $ do
    inHandle  <- inFile "inFile.txt"
    outHandle <- outFile "outFile.txt"
    liftIO (copy inHandle outHandle)

... or you can just wrap things inline:

main = runManaged $ do
    inHandle  <- managed (withFile "inFile.txt" ReadMode)
    outHandle <- managed (withFile "outFile.txt" WriteMode)
    liftIO (copy inHandle outHandle)

Additionally, since Managed is a Monad, you can take advantage of all your favorite combinators from Control.Monad. For example, the withMany function from Foreign.Marshal.Utils becomes a trivial wrapper around mapM:

withMany :: (a -> (b -> IO r) -> IO r) -> [a] -> ([b] -> IO r) -> IO r
withMany f = with . mapM (Managed . f)

Another reason to use Managed is that if you wrap a Monoid value in Managed you get back a new Monoid:

instance Monoid a => Monoid (Managed a)

This lets you combine managed resources transparently. You can also lift operations from some numeric type classes this way, too, such as the Num type class.

NOTE: Managed may leak space if used in an infinite loop like this example:

import Control.Monad
import Control.Monad.Managed

main = runManaged (forever (liftIO (print 1)))

If you need to acquire a resource for a long-lived loop, you can instead acquire the resource first and run the loop in IO, using either of the following two equivalent idioms:

with resource (\r -> forever (useThe r))

do r <- resource
   liftIO (forever (useThe r))

Managed

data Managed a

A managed resource that you acquire using with

Instances

Monad Managed

Defined in Control.Monad.Managed

Methods

(>>=) :: Managed a -> (a -> Managed b) -> Managed b

(>>) :: Managed a -> Managed b -> Managed b

return :: a -> Managed a

Functor Managed

Defined in Control.Monad.Managed

Methods

fmap :: (a -> b) -> Managed a -> Managed b

(<$) :: a -> Managed b -> Managed a

MonadFail Managed

Defined in Control.Monad.Managed

Methods

fail :: String -> Managed a

Applicative Managed

Defined in Control.Monad.Managed

Methods

pure :: a -> Managed a

(<*>) :: Managed (a -> b) -> Managed a -> Managed b

liftA2 :: (a -> b -> c) -> Managed a -> Managed b -> Managed c

(*>) :: Managed a -> Managed b -> Managed b

(<*) :: Managed a -> Managed b -> Managed a

MonadIO Managed

Defined in Control.Monad.Managed

Methods

liftIO :: IO a -> Managed a

MonadManaged Managed

Defined in Control.Monad.Managed

Methods

using :: Managed a -> Managed a

Floating a => Floating (Managed a)

Defined in Control.Monad.Managed

Methods

pi :: Managed a

exp :: Managed a -> Managed a

log :: Managed a -> Managed a

sqrt :: Managed a -> Managed a

(**) :: Managed a -> Managed a -> Managed a

logBase :: Managed a -> Managed a -> Managed a

sin :: Managed a -> Managed a

cos :: Managed a -> Managed a

tan :: Managed a -> Managed a

asin :: Managed a -> Managed a

acos :: Managed a -> Managed a

atan :: Managed a -> Managed a

sinh :: Managed a -> Managed a

cosh :: Managed a -> Managed a

tanh :: Managed a -> Managed a

asinh :: Managed a -> Managed a

acosh :: Managed a -> Managed a

atanh :: Managed a -> Managed a

log1p :: Managed a -> Managed a

expm1 :: Managed a -> Managed a

log1pexp :: Managed a -> Managed a

log1mexp :: Managed a -> Managed a

Fractional a => Fractional (Managed a)

Defined in Control.Monad.Managed

Methods

(/) :: Managed a -> Managed a -> Managed a

recip :: Managed a -> Managed a

fromRational :: Rational -> Managed a

Num a => Num (Managed a)

Defined in Control.Monad.Managed

Methods

(+) :: Managed a -> Managed a -> Managed a

(-) :: Managed a -> Managed a -> Managed a

(*) :: Managed a -> Managed a -> Managed a

negate :: Managed a -> Managed a

abs :: Managed a -> Managed a

signum :: Managed a -> Managed a

fromInteger :: Integer -> Managed a

Semigroup a => Semigroup (Managed a)

Defined in Control.Monad.Managed

Methods

(<>) :: Managed a -> Managed a -> Managed a

sconcat :: NonEmpty (Managed a) -> Managed a

stimes :: Integral b => b -> Managed a -> Managed a

Monoid a => Monoid (Managed a)

Defined in Control.Monad.Managed

Methods

mempty :: Managed a

mappend :: Managed a -> Managed a -> Managed a

mconcat :: [Managed a] -> Managed a

class MonadIO m => MonadManaged m where

You can embed a Managed action within any Monad that implements MonadManaged by using the using function

All instances must obey the following two laws:

using (return x) = return x

using (m >>= f) = using m >>= \x -> using (f x)

Methods

using :: Managed a -> m a

Instances

MonadManaged Managed

Defined in Control.Monad.Managed

Methods

using :: Managed a -> Managed a

MonadManaged m => MonadManaged (MaybeT m)

Defined in Control.Monad.Managed

Methods

using :: Managed a -> MaybeT m a

(Monoid w, MonadManaged m) => MonadManaged (WriterT w m)

Defined in Control.Monad.Managed

Methods

using :: Managed a -> WriterT w m a

(Monoid w, MonadManaged m) => MonadManaged (WriterT w m)

Defined in Control.Monad.Managed

Methods

using :: Managed a -> WriterT w m a

MonadManaged m => MonadManaged (StateT s m)

Defined in Control.Monad.Managed

Methods

using :: Managed a -> StateT s m a

MonadManaged m => MonadManaged (StateT s m)

Defined in Control.Monad.Managed

Methods

using :: Managed a -> StateT s m a

MonadManaged m => MonadManaged (ReaderT r m)

Defined in Control.Monad.Managed

Methods

using :: Managed a -> ReaderT r m a

MonadManaged m => MonadManaged (IdentityT m)

Defined in Control.Monad.Managed

Methods

using :: Managed a -> IdentityT m a

MonadManaged m => MonadManaged (ExceptT e m)

Defined in Control.Monad.Managed

Methods

using :: Managed a -> ExceptT e m a

MonadManaged m => MonadManaged (ContT r m)

Defined in Control.Monad.Managed

Methods

using :: Managed a -> ContT r m a

(Monoid w, MonadManaged m) => MonadManaged (RWST r w s m)

Defined in Control.Monad.Managed

Methods

using :: Managed a -> RWST r w s m a

(Monoid w, MonadManaged m) => MonadManaged (RWST r w s m)

Defined in Control.Monad.Managed

Methods

using :: Managed a -> RWST r w s m a

managed :: MonadManaged m => (forall r. (a -> IO r) -> IO r) -> m a

Build a Managed value

managed_ :: MonadManaged m => (forall r. IO r -> IO r) -> m ()

Like managed but for resource-less operations.

with :: Managed a -> (a -> IO r) -> IO r

Acquire a Managed value

This is a potentially unsafe function since it allows a resource to escape its scope. For example, you might use Managed to safely acquire a file handle, like this:

import qualified System.IO as IO

example :: Managed Handle
example = managed (IO.withFile "foo.txt" IO.ReadMode)

... and if you never used the with function then you would never run the risk of accessing the Handle after the file was closed. However, if you use with then you can incorrectly access the handle after the handle is closed, like this:

bad :: IO ()
bad = do
    handle <- with example return
    IO.hPutStrLn handle "bar"  -- This will fail because the handle is closed

... so only use with if you know what you are doing and you're returning a value that is not a resource being managed.

runManaged :: Managed () -> IO ()

Run a Managed computation, enforcing that no acquired resources leak

Re-exports

Control.Monad.IO.Class re-exports MonadIO

class 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:

• liftIO . return = return

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

Methods

liftIO :: IO a -> m a

Lift a computation from the IO monad.

Instances

MonadIO IO

Since: base-4.9.0.0

Defined in Control.Monad.IO.Class

Methods

liftIO :: IO a -> IO a

MonadIO Managed

Defined in Control.Monad.Managed

Methods

liftIO :: IO a -> Managed a

MonadIO m => MonadIO (MaybeT m)

Defined in Control.Monad.Trans.Maybe

Methods

liftIO :: IO a -> MaybeT m a

(Monoid w, MonadIO m) => MonadIO (WriterT w m)

Defined in Control.Monad.Trans.Writer.Strict

Methods

liftIO :: IO a -> WriterT w m a

(Monoid w, MonadIO m) => MonadIO (WriterT w m)

Defined in Control.Monad.Trans.Writer.Lazy

Methods

liftIO :: IO a -> WriterT w m a

MonadIO m => MonadIO (StateT s m)

Defined in Control.Monad.Trans.State.Strict

Methods

liftIO :: IO a -> StateT s m a

MonadIO m => MonadIO (StateT s m)

Defined in Control.Monad.Trans.State.Lazy

Methods

liftIO :: IO a -> StateT s m a

MonadIO m => MonadIO (ReaderT r m)

Defined in Control.Monad.Trans.Reader

Methods

liftIO :: IO a -> ReaderT r m a

MonadIO m => MonadIO (IdentityT m)

Defined in Control.Monad.Trans.Identity

Methods

liftIO :: IO a -> IdentityT m a

MonadIO m => MonadIO (ExceptT e m)

Defined in Control.Monad.Trans.Except

Methods

liftIO :: IO a -> ExceptT e m a

MonadIO m => MonadIO (ContT r m)

Defined in Control.Monad.Trans.Cont

Methods

liftIO :: IO a -> ContT r m a

(Monoid w, MonadIO m) => MonadIO (RWST r w s m)

Defined in Control.Monad.Trans.RWS.Strict

Methods

liftIO :: IO a -> RWST r w s m a

(Monoid w, MonadIO m) => MonadIO (RWST r w s m)

Defined in Control.Monad.Trans.RWS.Lazy

Methods

liftIO :: IO a -> RWST r w s m a