Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Fetching contributors…

Octocat-spinner-32-eaf2f5

Cannot retrieve contributors at this time

file 363 lines (245 sloc) 11.937 kb
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362
0.3

(Released on: Fri Dec 2 09:52:16 UTC 2011)

* Major new API which IMHO is easier to understand than the old one.

* On average about 60 times faster than the previous release!

* New package lifted-base providing lifted versions of functions from the base
  library. It exports the following modules:

  - Control.Exception.Lifted
  - Control.Concurrent.Lifted
  - Control.Concurrent.MVar.Lifted
  - System.Timeout.Lifted

  Not all modules from base are converted yet. If you need a lifted version of
  some function from base, just ask me to add it or send me a patch.


0.2.0.3

(Released on: Sat Aug 27 21:18:22 UTC 2011)

* Fixed issue #2
  https://github.com/basvandijk/monad-control/issues/2


0.2.0.2

(Released on: Mon Aug 8 09:16:08 UTC 2011)

* Switched to git on github.

* Tested with base-4.4 and ghc-7.2.1.

* Use the new cabal test-suite feature.


0.2.0.1

(Released on: Wed Mar 16 15:53:50 UTC 2011)

* Added laws for MonadTransControl and MonadControlIO

* Bug fix: Add proper laziness to the MonadTransControl instances
  of the lazy StateT, WriteT and RWST
  These all failed the law: control $ \run -> run t = t
  where t = return undefined

* Add INLINABLE pragmas for most public functions
  A simple benchmark showed some functions
  (bracket and mask) improving by 30%.


0.2

(Released on: Wed Feb 9 12:05:26 UTC 2011)

* Use RunInBase in the type of idLiftControl.

* Added this NEWS file.

* Only parameterize Run with t and use RankNTypes to quantify n and o
  -liftControl :: (Monad m, Monad n, Monad o) => (Run t n o -> m a) -> t m a
  +liftControl :: Monad m => (Run t -> m a) -> t m a

  -type Run t n o = forall b. t n b -> n (t o b)
  +type Run t = forall n o b. (Monad n, Monad o, Monad (t o)) => t n b -> n (t o b)

  Bumped version from 0.1 to 0.2 to indicate this breaking change in API.

* Added example of a derivation of liftControlIO.
  Really enlightening!


0.1

(Released on: Sat Feb 5 23:36:21 UTC 2011)

* Initial release

This is the announcement message sent to the Haskell mailinglists:
http://www.mail-archive.com/haskell@haskell.org/msg23278.html


Dear all,

Several attempts have been made to lift control operations (functions
that use monadic actions as input instead of just output) through
monad transformers:

MonadCatchIO-transformers[1] provided a type class that allowed to
overload some often used control operations (catch, block and
unblock). Unfortunately that library was limited to those operations.
It was not possible to use, say, alloca in a monad transformer. More
importantly however, the library was broken as was explained[2] by
Michael Snoyman. In response Michael created the MonadInvertIO type
class which solved the problems. Then Anders Kaseorg created the
monad-peel library which provided an even nicer implementation.

monad-control is a rewrite of monad-peel that uses CPS style
operations and exploits the RankNTypes language extension to simplify
and speedup most functions. A very preliminary and not yet fully
representative, benchmark shows that monad-control is on average about
2.6 times faster than monad-peel:

bracket: 2.4 x faster
bracket_: 3.1 x faster
catch: 1.8 x faster
try: 4.0 x faster
mask: 2.0 x faster

Note that, although the package comes with a test suite that passes, I
still consider it highly experimental.


API DOCS:

http://hackage.haskell.org/package/monad-control


INSTALLING:

$ cabal update
$ cabal install monad-control


TESTING:

The package contains a copy of the monad-peel test suite written by
Anders. You can perform the tests using:

$ cabal unpack monad-control
$ cd monad-control
$ cabal configure -ftest
$ cabal test


BENCHMARKING:

$ darcs get http://bifunctor.homelinux.net/~bas/bench-monad-peel-control/
$ cd bench-monad-peel-control
$ cabal configure
$ cabal build
$ dist/build/bench-monad-peel-control/bench-monad-peel-control


DEVELOPING:

The darcs repository will be hosted on code.haskell.org ones that
server is back online. For the time being you can get the repository
from:

$ darcs get http://bifunctor.homelinux.net/~bas/monad-control/


TUTORIAL:

This short unpolished tutorial will explain how to lift control
operations through monad transformers. Our goal is to lift a control
operation like:

foo ∷ M a → M a

where M is some monad, into a transformed monad like 'StateT M':

foo' ∷ StateT M a → StateT M a

The first thing we need to do is write an instance for the
MonadTransControl type class:

class MonadTrans t ⇒ MonadTransControl t where
  liftControl ∷ (Monad m, Monad n, Monad o)
              ⇒ (Run t n o → m a) → t m a

If you ignore the Run argument for now, you'll see that liftControl is
identical to the 'lift' method of the MonadTrans type class:

class MonadTrans t where
    lift ∷ Monad m ⇒ m a → t m a

So the instance for MonadTransControl will probably look very much
like the instance for MonadTrans. Let's see:

instance MonadTransControl (StateT s) where
    liftControl f = StateT $ \s → liftM (\x → (x, s)) (f run)

So what is this run function? Let's look at its type:

type Run t n o = ∀ b. t n b → n (t o b)

The run function executes a transformed monadic action 't n b' in the
non-transformed monad 'n'. In our case the 't' will be a StateT
computation. The only way to run a StateT computation is to give it
some state and the only state we have lying around is the one from the
outer computation: 's'. So let's run it on 's':

instance MonadTransControl (StateT s) where
    liftControl f =
        StateT $ \s →
          let run t = ... runStateT t s ...
          in liftM (\x → (x, s)) (f run)

Now that we are able to run a transformed monadic action, we're almost
done. Look at the type of Run again. The function should leave the
result 't o b' in the monad 'n'. This 't o b' computation should
contain the final state after running the supplied 't n b'
computation. In case of our StateT it should contain the final state
s':

instance MonadTransControl (StateT s) where
    liftControl f =
        StateT $ \s →
          let run t = liftM (\(x, s') → StateT $ \_ → return (x, s'))
                            (runStateT t s)
          in liftM (\x → (x, s)) (f run)

This final computation, "StateT $ \_ → return (x, s')", can later be
used to restore the final state. Now that we have our
MonadTransControl instance we can start using it. Recall that our goal
was to lift "foo ∷ M a → M a" into our StateT transformer yielding the
function "foo' ∷ StateT M a → StateT M a".

To define foo', the first thing we need to do is call liftControl:

foo' t = liftControl $ \run → ...

This captures the current state of the StateT computation and provides
us with the run function that allows us to run a StateT computation on
this captured state.

Now recall the type of liftControl ∷ (Run t n o → m a) → t m a. You
can see that in place of the ... we must fill in a value of type 'm
a'. In our case this will be a value of type 'M a'. We can construct
such a value by calling foo. However, foo expects an argument of type
'M a'. Fortunately we can provide one if we convert the supplied 't'
computation of type 'StateT M a' to 'M a' using our run function of
type ∀ b. StateT M b → M (StateT o b):

foo' t = ... liftControl $ \run → foo $ run t

However, note that the run function returns the final StateT
computation inside M. So the type of the right hand side is now
'StateT M (StateT o b)'. We would like to restore this final state. We
can do that using join:

foo' t = join $ liftControl $ \run → foo $ run t

That's it! Note that because it's so common to join after a
liftControl I provide an abstraction for it:

control = join ∘ liftControl

Allowing you to simplify foo' to:

foo' t = control $ \run → foo $ run t

Probably the most common control operations that you want to lift
through your transformers are IO operations. Think about: bracket,
alloca, mask, etc.. For this reason I provide the MonadControlIO type
class:

class MonadIO m ⇒ MonadControlIO m where
  liftControlIO ∷ (RunInBase m IO → IO a) → m a

Again, if you ignore the RunInBase argument, you will see that
liftControlIO is identical to the liftIO method of the MonadIO type
class:

class Monad m ⇒ MonadIO m where
    liftIO ∷ IO a → m a

Just like Run, RunInBase allows you to run your monadic computation
inside your base monad, which in case of liftControlIO is IO:

type RunInBase m base = ∀ b. m b → base (m b)

The instance for the base monad is trivial:

instance MonadControlIO IO where
    liftControlIO = idLiftControl

idLiftControl directly executes f and passes it a run function which
executes the given action and lifts the result r into the trivial
'return r' action:

idLiftControl ∷ Monad m ⇒ ((∀ b. m b → m (m b)) → m a) → m a
idLiftControl f = f $ liftM $ \r -> return r

The instances for the transformers are all identical. Let's look at
StateT and ReaderT:

instance MonadControlIO m ⇒ MonadControlIO (StateT s m) where
    liftControlIO = liftLiftControlBase liftControlIO

instance MonadControlIO m ⇒ MonadControlIO (ReaderT r m) where
    liftControlIO = liftLiftControlBase liftControlIO

The magic function is liftLiftControlBase. This function is used to
compose two liftControl operations, the outer provided by a
MonadTransControl instance and the inner provided as the argument:

liftLiftControlBase ∷ (MonadTransControl t, Monad base, Monad m, Monad (t m))
                    ⇒ ((RunInBase m base → base a) → m a)
                    → ((RunInBase (t m) base → base a) → t m a)
liftLiftControlBase lftCtrlBase =
  \f → liftControl $ \run →
         lftCtrlBase $ \runInBase →
           f $ liftM (join ∘ lift) ∘ runInBase ∘ run

Basically it captures the state of the outer monad transformer using
liftControl. Then it captures the state of the inner monad using the
supplied lftCtrlBase function. If you recall the identical definitions
of the liftControlIO methods: 'liftLiftControlBase liftControlIO' you
will see that this lftCtrlBase function is the recursive step of
liftLiftControlBase. If you use 'liftLiftControlBase liftControlIO' in
a stack of monad transformers a chain of liftControl operations is
created:

liftControl $ \run1 -> liftControl $ \run2 -> liftControl $ \run3 -> ...

This will recurse until we hit the base monad. Then
liftLiftControlBase will finally run f in the base monad supplying it
with a run function that is able to run a 't m a' computation in the
base monad. It does this by composing the run and runInBase functions.
Note that runInBase is basically the composition: '... ∘ run3 ∘ run2'.

However, just composing the run and runInBase functions is not enough.
Namely: runInBase ∘ run ∷ ∀ b. t m b → base (m (t m b)) while we need
to have ∀ b. t m b → base (t m b). So we need to lift the 'm (t m b)'
computation inside t yielding: 't m (t m b)' and then join that to get
't m b'.

Now that we have our MonadControlIO instances we can start using them.
Let's look at how to lift 'bracket' into a monad supporting
MonadControlIO. Before we do that I define a little convenience
function similar to 'control':

controlIO = join ∘ liftControlIO

Bracket just calls controlIO which captures the state of m and
provides us with a runInIO function which allows us to run an m
computation in IO:

bracket ∷ MonadControlIO m
        ⇒ m a → (a → m b) → (a → m c) → m c
bracket before after thing =
  controlIO $ \runInIO →
    E.bracket (runInIO before)
              (\m → runInIO $ m >>= after)
              (\m → runInIO $ m >>= thing)

I welcome any comments, questions or patches.

Regards,

Bas

[1] http://hackage.haskell.org/package/MonadCatchIO-transformers
[2] http://docs.yesodweb.com/blog/invertible-monads-exceptions-allocations/
[3] http://hackage.haskell.org/package/monad-peel
Something went wrong with that request. Please try again.