7ad55f8 · streamly · git.iko.soy

git.iko.soy/streamly

Add @since annotations, bump version, update changelog

commit7ad55f8e632526db68234bf3c69b8cbaa12b03ac authorHarendra Kumar <harendra.kumar@gmail.com> dateSat 5 May 2018, 02:02 (8 years ago) parentca0e9a9

9 files changed+241−18

compare with master

unifiedsplit

.travis.yml+2−2 Changelog.md+4−5 README.md+15−6 src/Streamly.hs+1 src/Streamly/Core.hs+4 src/Streamly/Prelude.hs+104 src/Streamly/Streams.hs+105−3 src/Streamly/Time.hs+4 streamly.cabal+2−2

.travis.yml+2−2

@@ -91,8 +91,8 @@ matrix:

9191 #- env: BUILD=cabal CABALVER=2.0 GHCVER=8.2.2

9292 # addons: {apt: {packages: [cabal-install-2.0,ghc-8.2.2], sources: [hvr-ghc]}}

9393

94− - env: BUILD=cabal CABALVER=2.2 GHCVER=8.4.1

95− addons: {apt: {packages: [cabal-install-2.2,ghc-8.4.1], sources: [hvr-ghc]}}

94+ - env: BUILD=cabal CABALVER=2.2 GHCVER=8.4.2

95+ addons: {apt: {packages: [cabal-install-2.2,ghc-8.4.2], sources: [hvr-ghc]}}

9696

9797 - env: BUILD=cabal CABALVER=head GHCVER=head

9898 addons: {apt: {packages: [cabal-install-head,ghc-head], sources: [hvr-ghc]}}

Changelog.md+4−5

@@ -1,4 +1,4 @@

1−## Unreleased

1+## 0.2.0

33### Breaking changes

44* Change the semantics of the Semigroup instance for `InterleavedT`, `AsyncT`

@@ -12,10 +12,8 @@

1212 To adapt to the new changes, replace `<>` with `splice` wherever it is used

1313 for stream types other than `StreamT`.

1414

15−* Change the semantics of `Alternative` instance. The `<|>` operator now has a

16− different behavior for each type. See the documentation for more details. To

17− adapt to this change replace any usage of `<|>` with `parallel` and

18− `empty` with `nil`.

15+* Remove the `Alternative` instance. To adapt to this change replace any usage

16+ of `<|>` with `parallel` and `empty` with `nil`.

1917* Stream type now defaults to the `StreamT` type unless explicitly specified

2018 using a type combinator or a monomorphic type. This change reduces puzzling

2119 type errors for beginners. It includes the following two changes:

@@ -38,6 +36,7 @@

3836

3937### Deprecations

4038* Deprecate and rename the following symbols:

39+ * `MonadAsync` to `MonadParallel`

4140 * `Streaming` to `IsStream`

4241 * `runStreaming` to `runStream`

4342 * `AsyncT` to `CoparallelT`

README.md+15−6

@@ -8,13 +8,13 @@

99## Stream`ing` `Concurrent`ly

1010

11−Streamly, short for stream concurrently, is a simple yet powerful streaming

11+Streamly, short for streaming concurrently, is a simple yet powerful streaming

1212library with concurrent merging and concurrent nested looping support. A stream

1313is just like a list except that it is a list of monadic actions rather than

1414pure values. Streamly streams can be generated, consumed, combined, or

1515transformed serially or concurrently. We can loop over a stream serially or

1616concurrently. We can also have serial or concurrent nesting of loops. For

17−those familiar with the list transformer concept this is a concurrent list

17+those familiar with the list transformer concept streamly is a concurrent list

1818transformer. Streamly uses standard composition abstractions. Concurrent

1919composition is just the same as serial composition except that we use a simple

2020combinator to request a concurrent composition instead of serial. The

@@ -37,10 +37,19 @@ and supports concurrency we can write FRP applications similar in concept to

3737[Yampa](https://hackage.haskell.org/package/Yampa) or

3838[reflex](https://hackage.haskell.org/package/reflex).

3939

40−Streamly has excellent performance, see

41−[streaming-benchmarks](https://github.com/composewell/streaming-benchmarks)

42−for a comparison of popular streaming libraries on micro-benchmarks. For

43−more information:

40+Why use streamly?

41+

42+ * Simple list like streaming API, if you know how to use lists then you know

43+ how to use streamly.

44+ * Powerful yet simple and scalable concurrency. There is no other package

45+ that provides such high level and flexible concurrency support.

46+ * Unifies the functionality of many other disparate packages in a single

47+ concise and simple API.

48+ * Best in class performance. See

49+ [streaming-benchmarks](https://github.com/composewell/streaming-benchmarks)

50+ for a comparison of popular streaming libraries on micro-benchmarks.

51+

52+ For more information:

4453

4554 * [Streamly.Tutorial](https://hackage.haskell.org/package/streamly-0.1.2/docs/Streamly-Tutorial.html) module in the haddock documentation for a detailed introduction

4655 * [examples](https://github.com/composewell/streamly/tree/master/examples) directory in the package for some simple practical examples

src/Streamly.hs+1

@@ -129,6 +129,7 @@ module Streamly

129129 , InterleavedT

130130 , AsyncT

131131 , ZipAsync

132+ , serially

132133 , interleaving

133134 , asyncly

134135 , zipping

src/Streamly/Core.hs+4

@@ -243,8 +243,12 @@ cosplice m1 m2 = Stream $ \_ stp sng yld -> do

243243-- | A monad that can perform concurrent or parallel IO operations. Streams

244244-- that can be composed concurrently require the underlying monad to be

245245-- 'MonadParallel'.

246+--

247+-- @since 0.2.0

246248type MonadParallel m = (MonadIO m, MonadBaseControl IO m, MonadThrow m)

247249

250+-- |

251+-- @since 0.1.0

248252{-# DEPRECATED MonadAsync "Please use MonadParallel instead." #-}

249253type MonadAsync m = MonadParallel m

250254

src/Streamly/Prelude.hs+104

@@ -145,6 +145,8 @@ import Streamly.Streams

145145------------------------------------------------------------------------------

146146

147147-- | Build a Stream by unfolding pure steps starting from a seed.

148+--

149+-- @since 0.1.0

148150unfoldr :: IsStream t => (b -> Maybe (a, b)) -> b -> t m a

149151unfoldr step = fromStream . go

150152 where

@@ -154,6 +156,8 @@ unfoldr step = fromStream . go

154156 Just (a, b) -> yld a (go b)

155157

156158-- | Build a Stream by unfolding monadic steps starting from a seed.

159+--

160+-- @since 0.1.0

157161unfoldrM :: (IsStream t, Monad m) => (b -> m (Maybe (a, b))) -> b -> t m a

158162unfoldrM step = fromStream . go

159163 where

@@ -164,11 +168,15 @@ unfoldrM step = fromStream . go

164168 Just (a, b) -> yld a (go b)

165169

166170-- | Construct a stream from a 'Foldable' container.

171+--

172+-- @since 0.2.0

167173{-# INLINE fromFoldable #-}

168174fromFoldable :: (IsStream t, Foldable f) => f a -> t m a

169175fromFoldable = Prelude.foldr cons nil

170176

171177-- | Same as 'fromFoldable'.

178+--

179+-- @since 0.1.0

172180{-# DEPRECATED each "Please use fromFoldable instead." #-}

173181{-# INLINE each #-}

174182each :: (IsStream t, Foldable f) => f a -> t m a

@@ -182,10 +190,14 @@ each = fromFoldable

182190-- hello

183191-- ["hello"]

184192-- @

193+--

194+-- @since 0.2.0

185195once :: (IsStream t, Monad m) => m a -> t m a

186196once = fromStream . S.once

187197

188198-- | Generate a stream by performing a monadic action @n@ times.

199+--

200+-- @since 0.1.1

189201replicateM :: (IsStream t, Monad m) => Int -> m a -> t m a

190202replicateM n m = fromStream $ go n

191203 where

@@ -195,6 +207,8 @@ replicateM n m = fromStream $ go n

195207 else m >>= \a -> yld a (go (cnt - 1))

196208

197209-- | Generate a stream by repeatedly executing a monadic action forever.

210+--

211+-- @since 0.2.0

198212repeatM :: (IsStream t, Monad m) => m a -> t m a

199213repeatM = fromStream . go

200214 where

@@ -202,6 +216,8 @@ repeatM = fromStream . go

202216 m >>= \a -> yld a (go m)

203217

204218-- | Iterate a pure function from a seed value, streaming the results forever.

219+--

220+-- @since 0.1.2

205221iterate :: IsStream t => (a -> a) -> a -> t m a

206222iterate step = fromStream . go

207223 where

@@ -209,6 +225,8 @@ iterate step = fromStream . go

209225

210226-- | Iterate a monadic function from a seed value, streaming the results

211227-- forever.

228+--

229+-- @since 0.1.2

212230iterateM :: (IsStream t, Monad m) => (a -> m a) -> a -> t m a

213231iterateM step = fromStream . go

214232 where

@@ -217,6 +235,8 @@ iterateM step = fromStream . go

217235 yld s (go a)

218236

219237-- | Read lines from an IO Handle into a stream of Strings.

238+--

239+-- @since 0.1.0

220240fromHandle :: (IsStream t, MonadIO m) => IO.Handle -> t m String

221241fromHandle h = fromStream go

222242 where

@@ -238,6 +258,8 @@ fromHandle h = fromStream go

238258-- >> runIdentity $ foldr (:) [] (serially $ fromFoldable [1,2,3])

239259-- [1,2,3]

240260-- @

261+--

262+-- @since 0.1.0

241263foldr :: Monad m => (a -> b -> b) -> b -> StreamT m a -> m b

242264foldr step acc m = go (toStream m)

243265 where

@@ -254,6 +276,8 @@ foldr step acc m = go (toStream m)

254276-- >> runIdentity $ foldrM (\\x xs -> return (x : xs)) [] (serially $ fromFoldable [1,2,3])

255277-- [1,2,3]

256278-- @

279+--

280+-- @since 0.2.0

257281{-# INLINE foldrM #-}

258282foldrM :: Monad m => (a -> b -> m b) -> b -> StreamT m a -> m b

259283foldrM step acc m = go (toStream m)

@@ -268,6 +292,8 @@ foldrM step acc m = go (toStream m)

268292-- user supplied extraction function (the third argument) at each step. This is

269293-- designed to work with the @foldl@ library. The suffix @x@ is a mnemonic for

270294-- extraction.

295+--

296+-- @since 0.2.0

271297{-# INLINE scanx #-}

272298scanx :: IsStream t => (x -> a -> x) -> x -> (x -> b) -> t m a -> t m b

273299scanx step begin done m = cons (done begin) $ fromStream $ go (toStream m) begin

@@ -279,6 +305,8 @@ scanx step begin done m = cons (done begin) $ fromStream $ go (toStream m) begin

279305 in yld (done s) (go r s)

280306 in S.runStream m1 Nothing stp single yield

281307

308+-- |

309+-- @since 0.1.1

282310{-# DEPRECATED scan "Please use scanx instead." #-}

283311scan :: IsStream t => (x -> a -> x) -> x -> (x -> b) -> t m a -> t m b

284312scan = scanx

@@ -287,6 +315,8 @@ scan = scanx

287315-- step, generating a stream of all intermediate fold results. The first

288316-- element of the stream is the user supplied initial value, and the last

289317-- element of the stream is the same as the result of 'foldl''.

318+--

319+-- @since 0.2.0

290320{-# INLINE scanl' #-}

291321scanl' :: IsStream t => (b -> a -> b) -> b -> t m a -> t m b

292322scanl' step begin m = scanx step begin id m

@@ -295,6 +325,8 @@ scanl' step begin m = scanx step begin id m

295325-- left fold, but applies a user supplied extraction function (the third

296326-- argument) to the folded value at the end. This is designed to work with the

297327-- @foldl@ library. The suffix @x@ is a mnemonic for extraction.

328+--

329+-- @since 0.2.0

298330{-# INLINE foldx #-}

299331foldx :: Monad m => (x -> a -> x) -> x -> (x -> b) -> StreamT m a -> m b

300332foldx step begin done m = get $ go (toStream m) begin

@@ -316,17 +348,23 @@ foldx step begin done m = get $ go (toStream m) begin

316348 in (S.runStream stream) Nothing undefined sng yld

317349 in (S.runStream m1) Nothing stop single yield

318350

351+-- |

352+-- @since 0.1.0

319353{-# DEPRECATED foldl "Please use foldx instead." #-}

320354foldl :: Monad m => (x -> a -> x) -> x -> (x -> b) -> StreamT m a -> m b

321355foldl = foldx

322356

323357-- | Strict left associative fold.

358+--

359+-- @since 0.2.0

324360{-# INLINE foldl' #-}

325361foldl' :: Monad m => (b -> a -> b) -> b -> StreamT m a -> m b

326362foldl' step begin m = foldx step begin id m

327363

328364-- XXX replace the recursive "go" with explicit continuations.

329365-- | Like 'foldx', but with a monadic step function.

366+--

367+-- @since 0.2.0

330368foldxM :: Monad m => (x -> a -> m x) -> m x -> (x -> m b) -> StreamT m a -> m b

331369foldxM step begin done m = go begin (toStream m)

332370 where

@@ -336,17 +374,23 @@ foldxM step begin done m = go begin (toStream m)

336374 yield a r = acc >>= \b -> go (step b a) r

337375 in (S.runStream m1) Nothing stop single yield

338376

377+-- |

378+-- @since 0.1.0

339379{-# DEPRECATED foldlM "Please use foldxM instead." #-}

340380foldlM :: Monad m => (x -> a -> m x) -> m x -> (x -> m b) -> StreamT m a -> m b

341381foldlM = foldxM

342382

343383-- | Like 'foldl'' but with a monadic step function.

384+--

385+-- @since 0.2.0

344386foldlM' :: Monad m => (b -> a -> m b) -> b -> StreamT m a -> m b

345387foldlM' step begin m = foldxM step (return begin) return m

346388

347389-- | Decompose a stream into its head and tail. If the stream is empty, returns

348390-- 'Nothing'. If the stream is non-empty, returns 'Just (a, ma)', where 'a' is

349391-- the head of the stream and 'ma' its tail.

392+--

393+-- @since 0.1.0

350394uncons :: (IsStream t, Monad m) => StreamT m a -> m (Maybe (a, t m a))

351395uncons m =

352396 let stop = return Nothing

@@ -355,6 +399,8 @@ uncons m =

355399 in (S.runStream (toStream m)) Nothing stop single yield

356400

357401-- | Write a stream of Strings to an IO Handle.

402+--

403+-- @since 0.1.0

358404toHandle :: MonadIO m => IO.Handle -> StreamT m String -> m ()

359405toHandle h m = go (toStream m)

360406 where

@@ -369,11 +415,15 @@ toHandle h m = go (toStream m)

369415------------------------------------------------------------------------------

370416

371417-- | Convert a stream into a list in the underlying monad.

418+--

419+-- @since 0.1.0

372420{-# INLINABLE toList #-}

373421toList :: Monad m => StreamT m a -> m [a]

374422toList = foldrM (\a xs -> return (a : xs)) []

375423

376424-- | Take first 'n' elements from the stream and discard the rest.

425+--

426+-- @since 0.1.0

377427{-# INLINE take #-}

378428take :: IsStream t => Int -> t m a -> t m a

379429take n m = fromStream $ go n (toStream m)

@@ -383,6 +433,8 @@ take n m = fromStream $ go n (toStream m)

383433 in if n1 <= 0 then stp else (S.runStream m1) ctx stp sng yield

384434

385435-- | Include only those elements that pass a predicate.

436+--

437+-- @since 0.1.0

386438{-# INLINE filter #-}

387439filter :: IsStream t => (a -> Bool) -> t m a -> t m a

388440filter p m = fromStream $ go (toStream m)

@@ -395,6 +447,8 @@ filter p m = fromStream $ go (toStream m)

395447 in (S.runStream m1) ctx stp single yield

396448

397449-- | End the stream as soon as the predicate fails on an element.

450+--

451+-- @since 0.1.0

398452{-# INLINE takeWhile #-}

399453takeWhile :: IsStream t => (a -> Bool) -> t m a -> t m a

400454takeWhile p m = fromStream $ go (toStream m)

@@ -407,6 +461,8 @@ takeWhile p m = fromStream $ go (toStream m)

407461 in (S.runStream m1) ctx stp single yield

408462

409463-- | Discard first 'n' elements from the stream and take the rest.

464+--

465+-- @since 0.1.0

410466drop :: IsStream t => Int -> t m a -> t m a

411467drop n m = fromStream $ go n (toStream m)

412468 where

@@ -420,6 +476,8 @@ drop n m = fromStream $ go n (toStream m)

420476

421477-- | Drop elements in the stream as long as the predicate succeeds and then

422478-- take the rest of the stream.

479+--

480+-- @since 0.1.0

423481{-# INLINE dropWhile #-}

424482dropWhile :: IsStream t => (a -> Bool) -> t m a -> t m a

425483dropWhile p m = fromStream $ go (toStream m)

@@ -432,6 +490,8 @@ dropWhile p m = fromStream $ go (toStream m)

432490 in (S.runStream m1) ctx stp single yield

433491

434492-- | Determine whether all elements of a stream satisfy a predicate.

493+--

494+-- @since 0.1.0

435495all :: Monad m => (a -> Bool) -> StreamT m a -> m Bool

436496all p m = go (toStream m)

437497 where

@@ -443,6 +503,8 @@ all p m = go (toStream m)

443503 in (S.runStream m1) Nothing (return True) single yield

444504

445505-- | Determine whether any of the elements of a stream satisfy a predicate.

506+--

507+-- @since 0.1.0

446508any :: Monad m => (a -> Bool) -> StreamT m a -> m Bool

447509any p m = go (toStream m)

448510 where

@@ -454,14 +516,20 @@ any p m = go (toStream m)

454516 in (S.runStream m1) Nothing (return False) single yield

455517

456518-- | Determine the sum of all elements of a stream of numbers

519+--

520+-- @since 0.1.0

457521sum :: (Monad m, Num a) => StreamT m a -> m a

458522sum = foldl (+) 0 id

459523

460524-- | Determine the product of all elements of a stream of numbers

525+--

526+-- @since 0.1.1

461527product :: (Monad m, Num a) => StreamT m a -> m a

462528product = foldl (*) 1 id

463529

464530-- | Extract the first element of the stream, if any.

531+--

532+-- @since 0.1.0

465533head :: Monad m => StreamT m a -> m (Maybe a)

466534head m =

467535 let stop = return Nothing

@@ -470,6 +538,8 @@ head m =

470538 in (S.runStream (toStream m)) Nothing stop single yield

471539

472540-- | Extract all but the first element of the stream, if any.

541+--

542+-- @since 0.1.1

473543tail :: (IsStream t, Monad m) => StreamT m a -> m (Maybe (t m a))

474544tail m =

475545 let stop = return Nothing

@@ -478,11 +548,15 @@ tail m =

478548 in (S.runStream (toStream m)) Nothing stop single yield

479549

480550-- | Extract the last element of the stream, if any.

551+--

552+-- @since 0.1.1

481553{-# INLINE last #-}

482554last :: Monad m => StreamT m a -> m (Maybe a)

483555last = foldl (\_ y -> Just y) Nothing id

484556

485557-- | Determine whether the stream is empty.

558+--

559+-- @since 0.1.1

486560null :: Monad m => StreamT m a -> m Bool

487561null m =

488562 let stop = return True

@@ -491,6 +565,8 @@ null m =

491565 in (S.runStream (toStream m)) Nothing stop single yield

492566

493567-- | Determine whether an element is present in the stream.

568+--

569+-- @since 0.1.0

494570elem :: (Monad m, Eq a) => a -> StreamT m a -> m Bool

495571elem e m = go (toStream m)

496572 where

@@ -501,6 +577,8 @@ elem e m = go (toStream m)

501577 in (S.runStream m1) Nothing stop single yield

502578

503579-- | Determine whether an element is not present in the stream.

580+--

581+-- @since 0.1.0

504582notElem :: (Monad m, Eq a) => a -> StreamT m a -> m Bool

505583notElem e m = go (toStream m)

506584 where

@@ -511,11 +589,15 @@ notElem e m = go (toStream m)

511589 in (S.runStream m1) Nothing stop single yield

512590

513591-- | Determine the length of the stream.

592+--

593+-- @since 0.1.0

514594length :: Monad m => StreamT m a -> m Int

515595length = foldl (\n _ -> n + 1) 0 id

516596

517597-- | Returns the elements of the stream in reverse order.

518598-- The stream must be finite.

599+--

600+-- @since 0.1.1

519601reverse :: (IsStream t) => t m a -> t m a

520602reverse m = fromStream $ go S.nil (toStream m)

521603 where

@@ -528,6 +610,8 @@ reverse m = fromStream $ go S.nil (toStream m)

528610

529611-- XXX replace the recursive "go" with continuation

530612-- | Determine the minimum element in a stream.

613+--

614+-- @since 0.1.0

531615minimum :: (Monad m, Ord a) => StreamT m a -> m (Maybe a)

532616minimum m = go Nothing (toStream m)

533617 where

@@ -543,6 +627,8 @@ minimum m = go Nothing (toStream m)

543627

544628-- XXX replace the recursive "go" with continuation

545629-- | Determine the maximum element in a stream.

630+--

631+-- @since 0.1.0

546632maximum :: (Monad m, Ord a) => StreamT m a -> m (Maybe a)

547633maximum m = go Nothing (toStream m)

548634 where

@@ -564,6 +650,8 @@ maximum m = go Nothing (toStream m)

564650

565651-- | Replace each element of the stream with the result of a monadic action

566652-- applied on the element.

653+--

654+-- @since 0.1.0

567655{-# INLINE mapM #-}

568656mapM :: (IsStream t, Monad m) => (a -> m b) -> t m a -> t m b

569657mapM f m = fromStream $ go (toStream m)

@@ -575,6 +663,8 @@ mapM f m = fromStream $ go (toStream m)

575663

576664-- | Apply a monadic action to each element of the stream and discard the

577665-- output of the action.

666+--

667+-- @since 0.1.0

578668mapM_ :: Monad m => (a -> m b) -> StreamT m a -> m ()

579669mapM_ f m = go (toStream m)

580670 where

@@ -586,6 +676,8 @@ mapM_ f m = go (toStream m)

586676

587677-- | Reduce a stream of monadic actions to a stream of the output of those

588678-- actions.

679+--

680+-- @since 0.1.0

589681sequence :: (IsStream t, Monad m) => t m (m a) -> t m a

590682sequence m = fromStream $ go (toStream m)

591683 where

@@ -599,10 +691,14 @@ sequence m = fromStream $ go (toStream m)

599691------------------------------------------------------------------------------

600692

601693-- | Zip two streams serially using a pure zipping function.

694+--

695+-- @since 0.1.0

602696zipWith :: IsStream t => (a -> b -> c) -> t m a -> t m b -> t m c

603697zipWith f m1 m2 = fromStream $ S.zipWith f (toStream m1) (toStream m2)

604698

605699-- | Zip two streams serially using a monadic zipping function.

700+--

701+-- @since 0.1.0

606702zipWithM :: IsStream t => (a -> b -> t m c) -> t m a -> t m b -> t m c

607703zipWithM f m1 m2 = fromStream $ go (toStream m1) (toStream m2)

608704 where

@@ -622,11 +718,15 @@ zipWithM f m1 m2 = fromStream $ go (toStream m1) (toStream m2)

622718

623719-- | Zip two streams concurrently (i.e. both the elements being zipped are

624720-- generated concurrently) using a pure zipping function.

721+--

722+-- @since 0.2.0

625723zipParallelWith :: (IsStream t, MonadParallel m)

626724 => (a -> b -> c) -> t m a -> t m b -> t m c

627725zipParallelWith f m1 m2 =

628726 fromStream $ S.zipParallelWith f (toStream m1) (toStream m2)

629727

728+-- |

729+-- @since 0.1.0

630730{-# DEPRECATED zipAsyncWith "Please use zipParallelWith instead." #-}

631731zipAsyncWith :: (IsStream t, MonadParallel m)

632732 => (a -> b -> c) -> t m a -> t m b -> t m c

@@ -634,6 +734,8 @@ zipAsyncWith = zipParallelWith

634734

635735-- | Zip two streams asyncly (i.e. both the elements being zipped are generated

636736-- concurrently) using a monadic zipping function.

737+--

738+-- @since 0.2.0

637739zipParallelWithM :: (IsStream t, MonadParallel m)

638740 => (a -> b -> t m c) -> t m a -> t m b -> t m c

639741zipParallelWithM f m1 m2 = fromStream $ Stream $ \_ stp sng yld -> do

@@ -641,6 +743,8 @@ zipParallelWithM f m1 m2 = fromStream $ Stream $ \_ stp sng yld -> do

641743 mb <- async m2

642744 (S.runStream (toStream (zipWithM f ma mb))) Nothing stp sng yld

643745

746+-- |

747+-- @since 0.1.0

644748{-# DEPRECATED zipAsyncWithM "Please use zipParallelWithM instead." #-}

645749zipAsyncWithM :: (IsStream t, MonadParallel m)

646750 => (a -> b -> t m c) -> t m a -> t m b -> t m c

src/Streamly/Streams.hs+105−3

@@ -80,6 +80,7 @@ module Streamly.Streams

8080

8181 -- * Type Adapters

8282 , streamly

83+ , serially -- deprecated

8384 , costreamly

8485 , interleaving -- deprecated

8586 , coparallely

@@ -126,12 +127,16 @@ import qualified Streamly.Core as S

126127

127128-- | Class of types that can represent a stream of elements of some type 'a' in

128129-- some monad 'm'.

130+--

131+-- @since 0.2.0

129132class IsStream t where

130133 toStream :: t m a -> S.Stream m a

131134 fromStream :: S.Stream m a -> t m a

132135

133136-- | Same as 'IsStream'.

134−{-# Deprecated Streaming "Please use IsStream instead." #-}

137+--

138+-- @since 0.1.0

139+{-# DEPRECATED Streaming "Please use IsStream instead." #-}

135140type Streaming = IsStream

136141

137142------------------------------------------------------------------------------

@@ -144,6 +149,8 @@ type Streaming = IsStream

144149-- > toList nil

145150-- []

146151-- @

152+--

153+-- @since 0.1.0

147154nil :: IsStream t => t m a

148155nil = fromStream S.nil

149156

@@ -158,6 +165,8 @@ infixr 5 `consM`

158165-- world

159166-- ["hello","world"]

160167-- @

168+--

169+-- @since 0.2.0

161170consM :: (IsStream t, Monad m) => m a -> t m a -> t m a

162171consM m r = fromStream $ S.consM m (toStream r)

163172

@@ -171,6 +180,8 @@ infixr 5 |:

171180-- world

172181-- ["hello","world"]

173182-- @

183+--

184+-- @since 0.2.0

174185(|:) :: (IsStream t, Monad m) => m a -> t m a -> t m a

175186(|:) = consM

176187

@@ -183,6 +194,8 @@ infixr 5 `cons`

183194-- > toList $ 1 \`cons` 2 \`cons` 3 \`cons` nil

184195-- [1,2,3]

185196-- @

197+--

198+-- @since 0.1.0

186199cons :: IsStream t => a -> t m a -> t m a

187200cons a r = fromStream $ S.cons a (toStream r)

188201

@@ -195,6 +208,7 @@ infixr 5 .:

195208-- [1,2,3]

196209-- @

197210--

211+-- @since 0.1.1

198212(.:) :: IsStream t => a -> t m a -> t m a

199213(.:) = cons

200214

@@ -244,6 +258,8 @@ streamFold svr step single blank m =

244258-- | Run a streaming composition, discard the results. By default it interprets

245259-- the stream as 'StreamT', to run other types of streams use the type adapting

246260-- combinators for example @runStream . 'parallely'@.

261+--

262+-- @since 0.2.0

247263runStream :: Monad m => StreamT m a -> m ()

248264runStream m = go (toStream m)

249265 where

@@ -254,7 +270,9 @@ runStream m = go (toStream m)

254270 in (S.runStream m1) Nothing stop single yield

255271

256272-- | Same as 'runStream'

257−{-# Deprecated runStreaming "Please use runStream instead." #-}

273+--

274+-- @since 0.1.0

275+{-# DEPRECATED runStreaming "Please use runStream instead." #-}

258276runStreaming :: (Monad m, IsStream t) => t m a -> m ()

259277runStreaming = runStream . adapt

260278

@@ -273,7 +291,8 @@ toSVar sv m = S.toStreamVar sv (toStream m)

273291-- computation. The returned action is exhaustible and must be drained once. If

274292-- not drained fully we may have a thread blocked forever and once exhausted it

275293-- will always return 'empty'.

276−

294+--

295+-- @since 0.1.0

277296async :: (IsStream t, MonadParallel m) => t m a -> m (t m a)

278297async m = do

279298 sv <- S.newStreamVar1 (SVarStyle Disjunction LIFO) (toStream m)

@@ -373,6 +392,7 @@ instance (MonadState s m CONSTRAINT) => MonadState s (STREAM m) where { \

373392-- Note that serial composition can be used to combine an infinite number of

374393-- streams as it explores only one stream at a time.

375394--

395+-- @since 0.1.0

376396newtype StreamT m a = StreamT {getStreamT :: S.Stream m a}

377397 deriving (Semigroup, Monoid, Functor, MonadTrans)

378398

@@ -387,6 +407,8 @@ instance IsStream StreamT where

387407-- | Polymorphic version of the 'Semigroup' operation '<>' of 'StreamT'.

388408-- Appends two streams sequentially, yielding all elements from the first

389409-- stream, and then all elements from the second stream.

410+--

411+-- @since 0.2.0

390412{-# INLINE splice #-}

391413splice :: IsStream t => t m a -> t m a -> t m a

392414splice m1 m2 = fromStream $ S.splice (toStream m1) (toStream m2)

@@ -444,9 +466,12 @@ MONAD_COMMON_INSTANCES(StreamT,)

444466-- Note that costreamly composition can only combine a finite number of

445467-- streams as it needs to retain state for each unfinished stream.

446468--

469+-- @since 0.2.0

447470newtype CostreamT m a = CostreamT {getCostreamT :: S.Stream m a}

448471 deriving (Functor, MonadTrans)

449472

473+-- |

474+-- @since 0.1.0

450475{-# DEPRECATED InterleavedT "Please use 'CostreamT' instead." #-}

451476type InterleavedT = CostreamT

452477

@@ -460,6 +485,8 @@ instance IsStream CostreamT where

460485

461486-- | Polymorphic version of the 'Semigroup' operation '<>' of 'CostreamT'.

462487-- Interleaves two streams, yielding one element from each stream alternately.

488+--

489+-- @since 0.2.0

463490{-# INLINE cosplice #-}

464491cosplice :: IsStream t => t m a -> t m a -> t m a

465492cosplice m1 m2 = fromStream $ S.cosplice (toStream m1) (toStream m2)

@@ -470,6 +497,8 @@ instance Semigroup (CostreamT m a) where

470497infixr 5 <=>

471498

472499-- | Same as 'cosplice'.

500+--

501+-- @since 0.1.0

473502{-# DEPRECATED (<=>) "Please use 'cosplice' instead." #-}

474503{-# INLINE (<=>) #-}

475504(<=>) :: IsStream t => t m a -> t m a -> t m a

@@ -545,9 +574,12 @@ MONAD_COMMON_INSTANCES(CostreamT,)

545574-- Note that this composition can be used to combine infinite number of streams

546575-- as it explores only a bounded number of streams at a time.

547576--

577+-- @since 0.2.0

548578newtype CoparallelT m a = CoparallelT {getCoparallelT :: S.Stream m a}

549579 deriving (Functor, MonadTrans)

550580

581+-- |

582+-- @since 0.1.0

551583{-# DEPRECATED AsyncT "Please use 'CoparallelT' instead." #-}

552584type AsyncT = CoparallelT

553585

@@ -562,6 +594,8 @@ instance IsStream CoparallelT where

562594-- | Polymorphic version of the 'Semigroup' operation '<>' of 'CoparallelT'.

563595-- Merges two streams possibly concurrently, preferring the

564596-- elements from the left one when available.

597+--

598+-- @since 0.2.0

565599{-# INLINE coparallel #-}

566600coparallel :: (IsStream t, MonadParallel m) => t m a -> t m a -> t m a

567601coparallel m1 m2 = fromStream $ S.coparallel (toStream m1) (toStream m2)

@@ -570,6 +604,8 @@ instance MonadParallel m => Semigroup (CoparallelT m a) where

570604 (<>) = coparallel

571605

572606-- | Same as 'coparallel'.

607+--

608+-- @since 0.1.0

573609{-# DEPRECATED (<|) "Please use 'coparallel' instead." #-}

574610{-# INLINE (<|) #-}

575611(<|) :: (IsStream t, MonadParallel m) => t m a -> t m a -> t m a

@@ -655,6 +691,7 @@ MONAD_COMMON_INSTANCES(CoparallelT, MONADPARALLEL)

655691-- Note that round robin composition can only combine a finite number of

656692-- streams as it needs to retain state for each unfinished stream.

657693--

694+-- @since 0.1.0

658695newtype ParallelT m a = ParallelT {getParallelT :: S.Stream m a}

659696 deriving (Functor, MonadTrans)

660697

@@ -668,6 +705,8 @@ instance IsStream ParallelT where

668705

669706-- | Polymorphic version of the 'Semigroup' operation '<>' of 'ParallelT'.

670707-- Merges two streams concurrently choosing elements from both fairly.

708+--

709+-- @since 0.2.0

671710{-# INLINE parallel #-}

672711parallel :: (IsStream t, MonadParallel m) => t m a -> t m a -> t m a

673712parallel m1 m2 = fromStream $ S.parallel (toStream m1) (toStream m2)

@@ -720,6 +759,7 @@ MONAD_COMMON_INSTANCES(ParallelT, MONADPARALLEL)

720759-- The 'Semigroup' instance of this type works the same way as that of

721760-- 'StreamT'.

722761--

762+-- @since 0.2.0

723763newtype ZipStreamM m a = ZipStreamM {getZipStreamM :: S.Stream m a}

724764 deriving (Functor, Semigroup, Monoid)

725765

@@ -751,9 +791,12 @@ instance Monad m => Applicative (ZipStreamM m) where

751791-- The 'Semigroup' instance of this type works the same way as that of

752792-- 'StreamT'.

753793--

794+-- @since 0.2.0

754795newtype ZipParallelM m a = ZipParallelM {getZipParallelM :: S.Stream m a}

755796 deriving (Functor, Semigroup, Monoid)

756797

798+-- |

799+-- @since 0.1.0

757800{-# DEPRECATED ZipAsync "Please use ZipParallelM instead." #-}

758801type ZipAsync = ZipParallelM

759802

@@ -770,49 +813,78 @@ instance MonadParallel m => Applicative (ZipParallelM m) where

770813-------------------------------------------------------------------------------

771814

772815-- | Adapt any specific stream type to any other specific stream type.

816+--

817+-- @since 0.1.0

773818adapt :: (IsStream t1, IsStream t2) => t1 m a -> t2 m a

774819adapt = fromStream . toStream

775820

776821-- | Fix the type of a polymorphic stream as 'StreamT'.

822+--

823+-- @since 0.2.0

777824streamly :: IsStream t => StreamT m a -> t m a

778825streamly = adapt

779826

827+-- | Same as 'streamly'.

828+--

829+-- @since 0.1.0

830+{-# DEPRECATED serially "Please use streamly instead." #-}

831+serially :: IsStream t => StreamT m a -> t m a

832+serially = streamly

833+

780834-- | Fix the type of a polymorphic stream as 'CostreamT'.

835+--

836+-- @since 0.2.0

781837costreamly :: IsStream t => CostreamT m a -> t m a

782838costreamly = adapt

783839

784840-- | Same as 'costreamly'.

841+--

842+-- @since 0.1.0

785843{-# DEPRECATED interleaving "Please use costreamly instead." #-}

786844interleaving :: IsStream t => CostreamT m a -> t m a

787845interleaving = costreamly

788846

789847-- | Fix the type of a polymorphic stream as 'CoparallelT'.

848+--

849+-- @since 0.2.0

790850coparallely :: IsStream t => CoparallelT m a -> t m a

791851coparallely = adapt

792852

793853-- | Same as 'coparallely'.

854+--

855+-- @since 0.1.0

794856{-# DEPRECATED asyncly "Please use coparallely instead." #-}

795857asyncly :: IsStream t => CoparallelT m a -> t m a

796858asyncly = coparallely

797859

798860-- | Fix the type of a polymorphic stream as 'ParallelT'.

861+--

862+-- @since 0.1.0

799863parallely :: IsStream t => ParallelT m a -> t m a

800864parallely = adapt

801865

802866-- | Fix the type of a polymorphic stream as 'ZipStreamM'.

867+--

868+-- @since 0.2.0

803869zipStreamly :: IsStream t => ZipStreamM m a -> t m a

804870zipStreamly = adapt

805871

806872-- | Same as 'zipStreamly'.

873+--

874+-- @since 0.1.0

807875{-# DEPRECATED zipping "Please use zipStreamly instead." #-}

808876zipping :: IsStream t => ZipStreamM m a -> t m a

809877zipping = zipStreamly

810878

811879-- | Fix the type of a polymorphic stream as 'ZipParallelM'.

880+--

881+-- @since 0.2.0

812882zipParallely :: IsStream t => ZipParallelM m a -> t m a

813883zipParallely = adapt

814884

815885-- | Same as 'zipParallely'.

886+--

887+-- @since 0.1.0

816888{-# DEPRECATED zippingAsync "Please use zipParallely instead." #-}

817889zippingAsync :: IsStream t => ZipParallelM m a -> t m a

818890zippingAsync = zipParallely

@@ -822,31 +894,43 @@ zippingAsync = zipParallely

822894-------------------------------------------------------------------------------

823895

824896-- | Same as @runStream@.

897+--

898+-- @since 0.1.0

825899{-# DEPRECATED runStreamT "Please use runStream instead." #-}

826900runStreamT :: Monad m => StreamT m a -> m ()

827901runStreamT = runStream

828902

829903-- | Same as @runStream . costreamly@.

904+--

905+-- @since 0.1.0

830906{-# DEPRECATED runInterleavedT "Please use 'runStream . interleaving' instead." #-}

831907runInterleavedT :: Monad m => InterleavedT m a -> m ()

832908runInterleavedT = runStream . costreamly

833909

834910-- | Same as @runStream . coparallely@.

911+--

912+-- @since 0.1.0

835913{-# DEPRECATED runAsyncT "Please use 'runStream . coparallely' instead." #-}

836914runAsyncT :: Monad m => CoparallelT m a -> m ()

837915runAsyncT = runStream . coparallely

838916

839917-- | Same as @runStream . parallely@.

918+--

919+-- @since 0.1.0

840920{-# DEPRECATED runParallelT "Please use 'runStream . parallely' instead." #-}

841921runParallelT :: Monad m => ParallelT m a -> m ()

842922runParallelT = runStream . parallely

843923

844924-- | Same as @runStream . zipping@.

925+--

926+-- @since 0.1.0

845927{-# DEPRECATED runZipStream "Please use 'runStream . zipStreamly instead." #-}

846928runZipStream :: Monad m => ZipStreamM m a -> m ()

847929runZipStream = runStream . zipStreamly

848930

849931-- | Same as @runStream . zippingAsync@.

932+--

933+-- @since 0.1.0

850934{-# DEPRECATED runZipAsync "Please use 'runStream . zipParallely instead." #-}

851935runZipAsync :: Monad m => ZipParallelM m a -> m ()

852936runZipAsync = runStream . zipParallely

@@ -857,24 +941,36 @@ runZipAsync = runStream . zipParallely

857941

858942-- | A serial IO stream of elements of type @a@. See 'StreamT' documentation

859943-- for more details.

944+--

945+-- @since 0.2.0

860946type Stream a = StreamT IO a

861947

862948-- | An interleaving serial IO stream of elements of type @a@. See 'CostreamT'

863949-- documentation for more details.

950+--

951+-- @since 0.2.0

864952type Costream a = CostreamT IO a

865953

866954-- | A demand driven left biased parallelly composing IO stream of elements of

867955-- type @a@. See 'CoparallelT' documentation for more details.

956+--

957+-- @since 0.2.0

868958type Coparallel a = CoparallelT IO a

869959

870960-- | A round robin parallelly composing IO stream of elements of type @a@.

871961-- See 'ParallelT' documentation for more details.

962+--

963+-- @since 0.2.0

872964type Parallel a = ParallelT IO a

873965

874966-- | An IO stream whose applicative instance zips streams serially.

967+--

968+-- @since 0.2.0

875969type ZipStream a = ZipStreamM IO a

876970

877971-- | An IO stream whose applicative instance zips streams parallely.

972+--

973+-- @since 0.2.0

878974type ZipParallel a = ZipParallelM IO a

879975

880976------------------------------------------------------------------------------

@@ -885,6 +981,8 @@ type ZipParallel a = ZipParallelM IO a

885981-- container of streams using the specified stream sum operation.

886982--

887983-- @foldWith 'parallel' $ map return [1..3]@

984+--

985+-- @since 0.1.0

888986{-# INLINABLE foldWith #-}

889987foldWith :: (IsStream t, Foldable f)

890988 => (t m a -> t m a -> t m a) -> f (t m a) -> t m a

@@ -895,6 +993,8 @@ foldWith f = foldr f nil

895993-- operation.

896994--

897995-- @foldMapWith 'parallel' return [1..3]@

996+--

997+-- @since 0.1.0

898998{-# INLINABLE foldMapWith #-}

899999foldMapWith :: (IsStream t, Foldable f)

9001000 => (t m b -> t m b -> t m b) -> (a -> t m b) -> f a -> t m b

@@ -902,6 +1002,8 @@ foldMapWith f g = foldr (f . g) nil

9021002

9031003-- | Like 'foldMapWith' but with the last two arguments reversed i.e. the

9041004-- monadic streaming function is the last argument.

1005+--

1006+-- @since 0.1.0

9051007{-# INLINABLE forEachWith #-}

9061008forEachWith :: (IsStream t, Foldable f)

9071009 => (t m b -> t m b -> t m b) -> f a -> (a -> t m b) -> t m b

src/Streamly/Time.hs+4

@@ -20,6 +20,8 @@ import Control.Concurrent (threadDelay)

2020

2121-- | Run an action forever periodically at the given frequency specified in per

2222-- second (Hz).

23+--

24+-- @since 0.1.0

2325periodic :: Int -> IO () -> IO ()

2426periodic freq action = do

2527 action

@@ -33,6 +35,8 @@ periodic freq action = do

3335-- of time in microseconds. The second argument is the frequency in per second

3436-- (Hz). The third argument is the action to run, the action is provided the

3537-- local time as an argument.

38+--

39+-- @since 0.1.0

3640withClock :: IO Int -> Int -> (Int -> IO ()) -> IO ()

3741withClock clock freq action = do

3842 t <- clock

streamly.cabal+2−2

@@ -1,5 +1,5 @@

11name: streamly

2−version: 0.1.2

2+version: 0.2.0

33synopsis: Beautiful Streaming, Concurrent and Reactive Composition

44description:

55 Streamly, short for streaming concurrently, is a simple yet powerful

@@ -50,7 +50,7 @@ homepage: https://github.com/composewell/streamly

5050bug-reports: https://github.com/composewell/streamly/issues

5151license: BSD3

5252license-file: LICENSE

53−tested-with: GHC==7.10.3, GHC==8.0.2, GHC==8.2.2, GHC==8.4.1

53+tested-with: GHC==7.10.3, GHC==8.0.2, GHC==8.2.2, GHC==8.4.2

5454author: Harendra Kumar

5555maintainer: harendra.kumar@gmail.com