managed-1.0.5: A monad for managed values

Safe Haskell | Safe
Language | Haskell98

Control.Monad.Managed

Contents

- Managed
- Re-exports

Description

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))

Synopsis

- data Managed a
- class MonadIO m => MonadManaged m where
- managed :: (forall r. (a -> IO r) -> IO r) -> Managed a
- managed_ :: (forall r. IO r -> IO r) -> Managed ()
- with :: Managed a -> (a -> IO r) -> IO r
- runManaged :: Managed () -> IO ()
- module Control.Monad.IO.Class

# Managed

data Managed a #

A managed resource that you acquire using `with`

Instances

Monad Managed # |
Methods (>>=) :: Managed a -> (a -> Managed b) -> Managed b # (>>) :: Managed a -> Managed b -> Managed b # return :: a -> Managed a # fail :: String -> Managed a #
Functor Managed # |
Methods fmap :: (a -> b) -> Managed a -> Managed b # (<$) :: a -> Managed b -> Managed a #
Applicative Managed # |
Methods pure :: a -> Managed a # (<*>) :: Managed (a -> b) -> Managed a -> Managed b # (*>) :: Managed a -> Managed b -> Managed b # (<*) :: Managed a -> Managed b -> Managed a #
MonadIO Managed # |
Methods liftIO :: IO a -> Managed a #
MonadManaged Managed # |
Methods using :: Managed a -> Managed a #
Floating a => Floating (Managed a) # |
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) # |
Methods (/) :: Managed a -> Managed a -> Managed a # recip :: Managed a -> Managed a # fromRational :: Rational -> Managed a #
Num a => Num (Managed a) # |
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 #
Monoid a => Monoid (Managed a) # |
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)

Minimal complete definition

using

Methods

using :: Managed a -> m a #

Instances

MonadManaged Managed # |
Methods using :: Managed a -> Managed a #
MonadManaged m => MonadManaged (MaybeT m) # |
Methods using :: Managed a -> MaybeT m a #
(Monoid w, MonadManaged m) => MonadManaged (WriterT w m) # |
Methods using :: Managed a -> WriterT w m a #
(Monoid w, MonadManaged m) => MonadManaged (WriterT w m) # |
Methods using :: Managed a -> WriterT w m a #
MonadManaged m => MonadManaged (StateT s m) # |
Methods using :: Managed a -> StateT s m a #
MonadManaged m => MonadManaged (StateT s m) # |
Methods using :: Managed a -> StateT s m a #
MonadManaged m => MonadManaged (IdentityT * m) # |
Methods using :: Managed a -> IdentityT * m a #
MonadManaged m => MonadManaged (ExceptT e m) # |
Methods using :: Managed a -> ExceptT e m a #
MonadManaged m => MonadManaged (ReaderT * r m) # |
Methods using :: Managed a -> ReaderT * r m a #
MonadManaged m => MonadManaged (ContT * r m) # |
Methods using :: Managed a -> ContT * r m a #
(Monoid w, MonadManaged m) => MonadManaged (RWST r w s m) # |
Methods using :: Managed a -> RWST r w s m a #
(Monoid w, MonadManaged m) => MonadManaged (RWST r w s m) # |
Methods using :: Managed a -> RWST r w s m a #

managed :: (forall r. (a -> IO r) -> IO r) -> Managed a #

Build a `Managed` value

managed_ :: (forall r. IO r -> IO r) -> Managed () #

Like `managed` but for resource-less operations.

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

Acquire a `Managed` value

runManaged :: Managed () -> IO () #

Run a `Managed` computation, enforcing that no acquired resources leak

# Re-exports

Control.Monad.IO.Class re-exports `MonadIO`

module Control.Monad.IO.Class