@@ -686,11 +686,17 @@ parReplicateM cfg n = parSequence cfg . Stream.replicate n
686686-------------------------------------------------------------------------------
687687
688688-- Note: we can use another API with two callbacks stop and yield if we want
689−-- the callback to be able to indicate end of stream.
689+-- the callback to be able to indicate end of stream. Or we can use a Maybe
690+-- stream where Nothing indicates end of stream.
691+
692+-- XXX Rename to parNewCallback
693+
694+-- | Returns an entangled pair of a callback and a stream i.e. whenever the
695+-- callback is called a value appears in the stream. The stream is infinite,
696+-- there is no way for the callback to indicate that it is done now.
690697--
691−-- | Generates a callback and a stream pair. The callback returned is used to
692−-- queue values to the stream. The stream is infinite, there is no way for the
693−-- callback to indicate that it is done now.
698+-- The callback queues a value to a concurrent channel associated with the
699+-- stream. The stream can be evaluated safely in any thread.
694700--
695701-- /Pre-release/
696702--
@@ -701,10 +707,13 @@ newCallbackStream = do
701707
702708 -- XXX Add our own thread-id to the SVar as we can not know the callback's
703709 -- thread-id and the callback is not run in a managed worker. We need to
704− -- handle this better.
710+ -- handle this better. The caller thread might be killed by the Channel if
711+ -- the stream evaluator dies.
712+ --
705713 liftIO myThreadId
706714 >>= modifyThread (workerThreads chan) (outputDoorBell chan)
707715
716+ -- XXX We can use a "Maybe a" here. Use Nothing to send a Stop event.
708717 let callback a =
709718 liftIO
710719 $ void
@@ -713,9 +722,22 @@ newCallbackStream = do
713722 -- XXX Use fromChannelD?
714723 return (callback, fromChannel chan)
715724
716−-- | Supplies a stream generating callback to a callback setter function. Each
717−-- invocation of the callback results in a value being generated in the
718−-- resulting stream.
725+-- XXX Rename this to parSetCallback. Also take the Channel config as argument.
726+-- What config can be set by user here?
727+--
728+-- XXX What happens if an exception occurs when evaluating the stream? The
729+-- result of callback can be used to communicate that. But we can only know
730+-- about the exception on the next callback call. For better handling the user
731+-- can supply an exception sender function as argument to fromCallback.
732+
733+-- | @fromCallback f@ creates an entangled pair of a callback and a stream i.e.
734+-- whenever the callback is called a value appears in the stream. The function
735+-- @f@ is invoked with the callback as argument, and the stream is returned.
736+-- @f@ would store the callback for calling it later for generating values in
737+-- the stream.
738+--
739+-- The callback queues a value to a concurrent channel associated with the
740+-- stream. The stream can be evaluated safely in any thread.
719741--
720742-- /Pre-release/
721743--