This library implements a monad transformer for suspendable computations, similar and related to free comonads. It allows to write continuation-based web frameworks, command line applications and similar interfaces, where you want to reenter a computation at arbitrary spots.

A computation of type ContinueT e f m a is a computation that may either conclude with a value of type a or suspend with a value of type e. Before suspending or concluding it may register a set of reentry spots of type f (ContinueT e f m a). These spots are collected and returned along with the suspension/conclusion value:

 newtype ContinueT e f m a

To run a ContinueT computation you can use the runContinueT function:

 runContinueT :: ContinueT e f m a
              -> m (Either e a, f (ContinueT e f m a))

The result is either a suspension value of type e or a conclusion of type a. In both cases you can reenter the computation at the registered spots. Example:

 type MyMonad = ContinueT () (Map String) Identity

 myComp :: MyMonad Integer
 myComp = do
     x <- continue (Right 3) (M.singleton "x" (Right 15))
     y <- continue (Right 4) (M.singleton "y" (Right 17))
     return (x + y)

When you first run this computation the result will be the conclusion 3 + 4. Since MyMonad transforms to Identity we can use the convenience type alias Continue and the function runContinue:

 type MyMonad = Continue () (Map String)

 runContinue myComp
 = (Right 7, reentryMap)

Along with the result you will also get a reentry map of type Map String (MyMonad Integer). If you run the computation indexed by "x", you will get the result 15 + 4. This iteration itself will return a new reentry map on its part. That map will contain only the reentry spot "y", because the reentry indexed by "x" does not register itself again.

You can use the more general addCont function to register arbitrary reentry spots, which themselves are allowed to register new spots. Also In some kinds of applications you would want to combine the reentry maps produced. You can use the <!> function to do that:

 let overallReentryMap = reentryMap1 <!> reentryMap2

Since e is required to be a monoid, ContinueT forms a family of alternative functors that implement choice based on suspension and conclusion. The computation empty always suspends with mempty.

 x <|> y

This computation concludes with the conclusion of either x or y trying them in that order, or suspends if both of them suspend. Note that both computations are performed to their conclusion or suspension. This allows y both to have monadic effects as well as to register reentry points, even if x concludes.

There is also a combinator orElse that tries y only if x actually suspends. In that case, if x concludes, then y cannot register reentry spots or have effects in the underlying monad.