This module defines the Coroutine monad transformer.

A Coroutine monadic computation can suspend its execution at any time, returning to its invoker. The returned coroutine suspension contains the continuation of the coroutine embedded in a functor. Here is an example of a coroutine that suspends computation in the IO monad using the functor Yield:

 producer = do yield 1
               lift (putStrLn "Produced one, next is four.")
               yield 4
               return "Finished"

A suspended Coroutine computation can be resumed. The easiest way to run a coroutine is by using the pogoStick function, which keeps resuming the coroutine in trampolined style until it completes. Here is an example of pogoStick applied to the producer above:

 printProduce :: Show x => Coroutine (Yield x) IO r -> IO r
 printProduce producer = pogoStick (\(Yield x cont) -> lift (print x) >> cont) producer

Multiple concurrent coroutines can be run as well, and this module provides two different ways. The function seesaw can be used to run two interleaved computations. Another possible way is to weave together steps of different coroutines into a single coroutine using the function couple, which can then be executed by pogoStick.

Coroutines can be run from within another coroutine. In this case, the nested coroutines would normally suspend to their invoker. Another option is to allow a nested coroutine to suspend both itself and its invoker at once. In this case, the two suspension functors should be grouped into an EitherFunctor. To run nested coroutines of this kind, use functions pogoStickNested, seesawNested, and coupleNested.

For other uses of trampoline-style coroutines, see

 Trampolined Style - Ganz, S. E. Friedman, D. P. Wand, M, ACM SIGPLAN NOTICES, 1999, VOL 34; NUMBER 9, pages 18-27

and

 The Essence of Multitasking - William L. Harrison, Proceedings of the 11th International Conference on Algebraic
 Methodology and Software Technology, volume 4019 of Lecture Notes in Computer Science, 2006