@@ -796,9 +796,18 @@ pushOneToCtx ctype m = do
796796 pushWorker ctx
797797 return ctx
798798
799+-- XXX The async API is useful for exploring each stream arbitrarily when
800+-- zipping or merging two streams. We can use a newtype wrapper with a monad
801+-- instance that composes like regular streaming libraries to facilitate linear
802+-- composition. We will also need a yield API for that.
803+
799804-- | Run a computation asynchronously, triggers the computation and returns
800−-- another computation (i.e. a promise) that when run produces the output from
801−-- the original computation.
805+-- another computation (i.e. a promise) that when executed produces the output
806+-- from the original computation. Note that the returned action must be
807+-- executed exactly once and drained completely. If not executed or not drained
808+-- fully we will may have a thread blocked forever and if executed more than
809+-- once a ContextUsedAfterEOF exception will be raised.
810+
802811async :: MonadAsync m => AsyncT m a -> m (AsyncT m a)
803812async m = do
804813 ctx <- pushOneToCtx (CtxType Disjunction LIFO) m