This module defines the Coroutine monad transformer.

A Coroutine monadic computation can suspend its execution at any time, returning control to its invoker. The returned suspension value contains the coroutine's resumption wrapped in a Functor. Here is an example of a coroutine in the IO monad that suspends computation using the functor Yield from the Control.Monad.Coroutine.SuspensionFunctors module:

producer :: Coroutine (Yield Int) IO String
producer = do yield 1
              lift (putStrLn "Produced one, next is four.")
              yield 4
              return "Finished"

To continue the execution of a suspended Coroutine, extract it from the suspension functor and apply its resume method. The easiest way to run a coroutine to completion is by using the pogoStick function, which keeps resuming the coroutine in trampolined style until it completes. Here is one way to apply pogoStick to the producer example 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. To run two interleaved computations, use a WeaveStepper to weave together steps of two different coroutines into a single coroutine, which can then be executed by pogoStick.

For various uses of trampoline-style coroutines, see

Coroutine Pipelines - Mario Blažević, The Monad.Reader issue 19, pages 29-50

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