@@ -796,9 +796,18 @@ pushOneToCtx ctype m = do
796 pushWorker ctx
796 pushWorker ctx
797 return ctx
797 return ctx
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.
799-- | Run a computation asynchronously, triggers the computation and returns
804-- | Run a computation asynchronously, triggers the computation and returns
800−-- another computation (i.e. a promise) that when run produces the output from
805+-- another computation (i.e. a promise) that when executed produces the output
801−-- the original computation.
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.
802async :: MonadAsync m => AsyncT m a -> m (AsyncT m a)
811async :: MonadAsync m => AsyncT m a -> m (AsyncT m a)
803async m = do
812async m = do
804 ctx <- pushOneToCtx (CtxType Disjunction LIFO) m
813 ctx <- pushOneToCtx (CtxType Disjunction LIFO) m