@@ -27,14 +27,27 @@ module Streamly.Internal.Data.Fold.Container
2727 -- | Direct values in the input stream to different folds using an n-ary
2828 -- fold selector. 'demux' is a generalization of 'classify' (and
2929 -- 'partition') where each key of the classifier can use a different fold.
30− , demuxKvToContainer
31− , demuxKvToMap
30+ --
31+ -- You need to see only 'demux' if you are looking to find the capabilities
32+ -- of these combinators, all others are variants of that.
3233
34+ -- *** Output is a container
35+ -- | The fold state snapshot returns the key-value container of in-progress
36+ -- folds.
3337 , demuxToContainer
3438 , demuxToContainerIO
3539 , demuxToMap
3640 , demuxToMapIO
3741
42+ -- *** Input is explicit key-value tuple
43+ -- | Like above but inputs are in explicit key-value pair form.
44+ , demuxKvToContainer
45+ , demuxKvToMap
46+
47+ -- *** Scan of finished fold results
48+ -- | Like above, but the resulting fold state snapshot contains the key
49+ -- value container as well as the finished key result if a fold in the
50+ -- container finished.
3851 , demuxGeneric
3952 , demux
4053 , demuxGenericIO
@@ -251,6 +264,9 @@ countDistinctInt = fmap (\(Tuple' _ n) -> n) $ foldl' step initial
251264-- because key is to be determined on each input whereas fold is to be
252265-- determined only once for a key.
253266
267+-- | This is the most general of all demux, classify operations.
268+--
269+-- See 'demux' for documentation.
254270{-# INLINE demuxGeneric #-}
255271demuxGeneric :: (Monad m, IsMap f, Traversable f) =>
256272 (a -> Key f)
@@ -294,11 +310,18 @@ demuxGeneric getKey getFold = fmap extract $ foldlM' step initial
294310 Partial s -> e s
295311 Done b -> return b
296312
297−-- | In a key value stream, fold values corresponding to each key with a key
298−-- specific fold. The fold returns the fold result as the second component of
299−-- the output tuple whenever a fold terminates. The first component of the
300−-- tuple is a Map of in-progress folds. If a fold terminates, another
301−-- instance of the fold is started upon receiving an input with that key.
313+-- | @demux getKey getFold@: In a key value stream, fold values corresponding
314+-- to each key using a key specific fold. @getFold@ is invoked to generate a
315+-- key specific fold when a key is encountered for the first time in the
316+-- stream.
317+--
318+-- The first component of the output tuple is a key-value Map of in-progress
319+-- folds. The fold returns the fold result as the second component of the
320+-- output tuple whenever a fold terminates.
321+--
322+-- If a fold terminates, another instance of the fold is started upon receiving
323+-- an input with that key, @getFold@ is invoked again whenever the key is
324+-- encountered again.
302325--
303326-- This can be used to scan a stream and collect the results from the scan
304327-- output.
@@ -312,6 +335,8 @@ demux :: (Monad m, Ord k) =>
312335 -> Fold m a (m (Map k b), Maybe (k, b))
313336demux = demuxGeneric
314337
338+-- | This is specialized version of 'demuxGeneric' that uses mutable IO cells
339+-- as fold accumulators for better performance.
315340{-# INLINE demuxGenericIO #-}
316341demuxGenericIO :: (MonadIO m, IsMap f, Traversable f) =>
317342 (a -> Key f)
@@ -377,6 +402,9 @@ demuxGenericIO getKey getFold = fmap extract $ foldlM' step initial
377402-- | This is specialized version of 'demux' that uses mutable IO cells as
378403-- fold accumulators for better performance.
379404--
405+-- Keep in mind that the values in the returned Map may be changed by the
406+-- ongoing fold if you are using those concurrently in another thread.
407+--
380408{-# INLINE demuxIO #-}
381409demuxIO :: (MonadIO m, Ord k) =>
382410 (a -> k)