1{-# LANGUAGE BangPatterns #-}
3{-# LANGUAGE ConstraintKinds #-}
4{-# LANGUAGE FlexibleContexts #-}
5{-# LANGUAGE FlexibleInstances #-}
6{-# LANGUAGE InstanceSigs #-}
7{-# LANGUAGE MultiParamTypeClasses #-}
8{-# LANGUAGE PatternSynonyms #-}
9{-# LANGUAGE ViewPatterns #-}
10{-# LANGUAGE RankNTypes #-}
11{-# LANGUAGE UndecidableInstances #-} -- XXX
14-- Module : Streamly.Streams.StreamKType
15-- Copyright : (c) 2017 Harendra Kumar
18-- Maintainer : harendra.kumar@gmail.com
19-- Stability : experimental
23-- Continuation passing style (CPS) stream implementation. The symbol 'K' below
24-- denotes a function as well as a Kontinuation.
26module Streamly.Streams.StreamKType
28 -- * A class for streams
54 , Streaming -- deprecated
58import Control.Monad (void)
59import Control.Monad.IO.Class (MonadIO(liftIO))
60import Control.Monad.Trans.Class (MonadTrans(lift))
61import Data.Semigroup (Semigroup(..))
62import Prelude hiding (map)
66------------------------------------------------------------------------------
68------------------------------------------------------------------------------
70-- | The type @Stream m a@ represents a monadic stream of values of type 'a'
71-- constructed using actions in monad 'm'. It uses stop, singleton and yield
72-- continuations equivalent to the following direct style type:
75-- data Stream m a = Stop | Singleton a | Yield a (Stream m a)
78-- To facilitate parallel composition we maintain a local state in an 'SVar'
79-- that is shared across and is used for synchronization of the streams being
82-- The singleton case can be expressed in terms of stop and yield but we have
83-- it as a separate case to optimize composition operations for streams with
84-- single element. We build singleton streams in the implementation of 'pure'
85-- for Applicative and Monad, and in 'lift' for MonadTrans.
87-- XXX remove the Stream type parameter from State as it is always constant.
88-- We can remove it from SVar as well
92 State Stream m a -- state
93 -> (a -> Stream m a -> m r) -- yield
94 -> (a -> m r) -- singleton
99------------------------------------------------------------------------------
100-- Types that can behave as a Stream
101------------------------------------------------------------------------------
106-- XXX Use a different SVar based on the stream type. But we need to make sure
107-- that we do not lose performance due to polymorphism.
109-- | Class of types that can represent a stream of elements of some type 'a' in
113class IsStream t where
114 toStream :: t m a -> Stream m a
115 fromStream :: Stream m a -> t m a
116 -- | Constructs a stream by adding a monadic action at the head of an
117 -- existing stream. For example:
120 -- > toList $ getLine \`consM` getLine \`consM` nil
126 -- /Concurrent (do not use 'parallely' to construct infinite streams)/
129 consM :: MonadAsync m => m a -> t m a -> t m a
130 -- | Operator equivalent of 'consM'. We can read it as "@parallel colon@"
131 -- to remember that @|@ comes before ':'.
134 -- > toList $ getLine |: getLine |: nil
141 -- let delay = threadDelay 1000000 >> print 1
142 -- runStream $ serially $ delay |: delay |: delay |: nil
143 -- runStream $ parallely $ delay |: delay |: delay |: nil
146 -- /Concurrent (do not use 'parallely' to construct infinite streams)/
149 (|:) :: MonadAsync m => m a -> t m a -> t m a
150 -- We can define (|:) just as 'consM' but it is defined explicitly for each
151 -- type because we want to use SPECIALIZE pragma on the definition.
153-- | Same as 'IsStream'.
156{-# DEPRECATED Streaming "Please use IsStream instead." #-}
157type Streaming = IsStream
159-------------------------------------------------------------------------------
160-- Type adapting combinators
161-------------------------------------------------------------------------------
163-- XXX Move/reset the State here by reconstructing the stream with cleared
164-- state. Can we make sure we do not do that when t1 = t2? If we do this then
165-- we do not need to do that explicitly using svarStyle. It would act as
166-- unShare when the stream type is the same.
168-- | Adapt any specific stream type to any other specific stream type.
171adapt :: (IsStream t1, IsStream t2) => t1 m a -> t2 m a
172adapt = fromStream . toStream
174------------------------------------------------------------------------------
176------------------------------------------------------------------------------
178-- XXX The State is always parameterized by "Stream" which means State is not
179-- different for different stream types. So we have to manually make sure that
180-- when converting from one stream to another we migrate the state correctly.
181-- This can be fixed if we use a different SVar type for different streams.
182-- Currently we always use "SVar Stream" and therefore a different State type
183-- parameterized by that stream.
185-- | Build a stream from an 'SVar', a stop continuation, a singleton stream
186-- continuation and a yield continuation.
188 => (forall r. State Stream m a
189 -> (a -> t m a -> m r)
194mkStream k = fromStream $ MkStream $ \st yld sng stp ->
195 let yieldk a r = yld a (toStream r)
196 in k st yieldk sng stp
198-- | A terminal function that has no continuation to follow.
199type StopK m = forall r. m r -> m r
201-- | A monadic continuation, it is a function that yields a value of type "a"
202-- and calls the argument (a -> m r) as a continuation with that value. We can
203-- also think of it as a callback with a handler (a -> m r). Category
204-- theorists call it a codensity type, a special type of right kan extension.
205type YieldK m a = forall r. (a -> m r) -> m r
207_wrapM :: Monad m => m a -> YieldK m a
208_wrapM m = \k -> m >>= k
210-- | Make an empty stream from a stop function.
211fromStopK :: IsStream t => StopK m -> t m a
212fromStopK k = mkStream $ \_ _ _ stp -> k stp
214-- | Make a singleton stream from a yield function.
215fromYieldK :: IsStream t => YieldK m a -> t m a
216fromYieldK k = mkStream $ \_ _ sng _ -> k sng
218-- | Add a yield function at the head of the stream.
219consK :: IsStream t => YieldK m a -> t m a -> t m a
220consK k r = mkStream $ \_ yld _ _ -> k (\x -> yld x r)
222-- XXX Build a stream from a repeating callback function.
224------------------------------------------------------------------------------
226------------------------------------------------------------------------------
228-- | Fold a stream by providing an SVar, a stop continuation, a singleton
229-- continuation and a yield continuation. The stream would share the current
230-- SVar passed via the State.
231{-# INLINE foldStreamShared #-}
235 -> (a -> t m a -> m r)
240foldStreamShared st yld sng stp m =
241 let yieldk a x = yld a (fromStream x)
242 MkStream k = toStream m
243 in k st yieldk sng stp
245-- | Fold a stream by providing a State, stop continuation, a singleton
246-- continuation and a yield continuation. The stream will not use the SVar
248{-# INLINE foldStream #-}
252 -> (a -> t m a -> m r)
257foldStream st yld sng stp m =
258 let yieldk a x = yld a (fromStream x)
259 MkStream k = toStream m
260 in k (adaptState st) yieldk sng stp
262-- Run the stream using a run function associated with the SVar that runs the
263-- streams with a captured snapshot of the monadic state.
264{-# INLINE foldStreamSVar #-}
266 :: (IsStream t, MonadIO m)
268 -> State Stream m a -- state
269 -> (a -> t m a -> m r) -- yield
270 -> (a -> m r) -- singleton
274foldStreamSVar sv st yld sng stp m =
275 let mrun = runInIO $ svarMrun sv
276 in void $ liftIO $ mrun $ foldStreamShared st yld sng stp m
278-------------------------------------------------------------------------------
280-------------------------------------------------------------------------------
282{-# INLINE consMSerial #-}
283consMSerial :: (IsStream t, Monad m) => m a -> t m a -> t m a
284consMSerial m r = mkStream $ \_ yld _ _ -> m >>= \a -> yld a r
286-------------------------------------------------------------------------------
288-------------------------------------------------------------------------------
290instance IsStream Stream where
295 {-# SPECIALIZE consM :: IO a -> Stream IO a -> Stream IO a #-}
296 consM :: Monad m => m a -> Stream m a -> Stream m a
300 {-# SPECIALIZE (|:) :: IO a -> Stream IO a -> Stream IO a #-}
301 (|:) :: Monad m => m a -> Stream m a -> Stream m a
304------------------------------------------------------------------------------
306------------------------------------------------------------------------------
308-- | Polymorphic version of the 'Semigroup' operation '<>' of 'SerialT'.
309-- Appends two streams sequentially, yielding all elements from the first
310-- stream, and then all elements from the second stream.
314serial :: IsStream t => t m a -> t m a -> t m a
317 go m = mkStream $ \st yld sng stp ->
318 let stop = foldStream st yld sng stp m2
320 yieldk a r = yld a (go r)
321 in foldStream st yieldk single stop m
323instance Semigroup (Stream m a) where
326------------------------------------------------------------------------------
328------------------------------------------------------------------------------
338nil :: IsStream t => t m a
339nil = mkStream $ \_ _ _ stp -> stp
341instance Monoid (Stream m a) where
345-------------------------------------------------------------------------------
347-------------------------------------------------------------------------------
351map :: (IsStream t, Monad m) => (a -> b) -> t m a -> t m b
352map f m = mkStream $ \st yld sng stp ->
354 yieldk a r = yld (f a) (map f r)
355 in foldStream (adaptState st) yieldk single stp m
357instance Monad m => Functor (Stream m) where
360-------------------------------------------------------------------------------
362-------------------------------------------------------------------------------
365yieldM :: (Monad m, IsStream t) => m a -> t m a
366yieldM m = fromStream $ mkStream $ \_ _ single _ -> m >>= single
368instance MonadTrans Stream where
keysesc to close
- j k
- move down, up
- enter
- open
- esc
- back, or up a level
- 1 2 3 4
- readme, files, commits, refs
- /
- filter
- y
- copy the clone command
- c
- compare the chosen commit with another (or shift-click both)
- ?
- show or hide this list