30f69ab · streamly · git.iko.soy

git.iko.soy/streamly

Add comments about unfold exception/resource mgmt ops

commit30f69ab04513bbe5f25d2f16e57f40bd441e43de authorHarendra Kumar <harendra@composewell.com> dateThu 8 Dec 2022, 06:25 (4 years ago) parentccbf1e4

4 files changed+16−2

compare with master

unifiedsplit

core/src/Streamly/Data/Unfold.hs+5 core/src/Streamly/Internal/Data/Unfold.hs+9 core/src/Streamly/Internal/FileSystem/File.hs+1−1 src/Streamly/Internal/Network/Inet/TCP.hs+1−1

core/src/Streamly/Data/Unfold.hs+5

@@ -205,6 +205,11 @@ module Streamly.Data.Unfold

205205

206206 -- ** Nesting

207207 , many

208+

209+ -- Exception combinators are not exposed, we would like to encourage the

210+ -- use of Stream type instead where exception handling is required. We can

211+ -- consider exposing the unfold exception functions if there is a

212+ -- compelling use case to use unfolds instead of stream.

208213 )

209214where

210215

core/src/Streamly/Internal/Data/Unfold.hs+9

@@ -247,6 +247,11 @@ module Streamly.Internal.Data.Unfold

247247 , bind

248248

249249 -- ** Resource Management

250+ -- | 'bracket' is the most general resource management operation, all other

251+ -- operations can be expressed using it. These functions have IO suffix

252+ -- because the allocation and cleanup functions are IO actions. For

253+ -- generalized allocation and cleanup functions see the functions without

254+ -- the IO suffix in the "streamly" package.

250255 , gbracket_

251256 , gbracketIO

252257 , before

@@ -258,6 +263,10 @@ module Streamly.Internal.Data.Unfold

258263 , bracket_

259264

260265 -- ** Exceptions

266+ -- | Most of these combinators inhibit stream fusion, therefore, when

267+ -- possible, they should be called in an outer loop to mitigate the cost.

268+ -- For example, instead of calling them on a stream of chars call them on a

269+ -- stream of arrays before flattening it to a stream of chars.

261270 , onException

262271 , handle

263272 )

core/src/Streamly/Internal/FileSystem/File.hs+1−1

@@ -113,9 +113,9 @@ import Streamly.Internal.System.IO (defaultChunkSize)

113113

114114import qualified Streamly.Data.Array as A

115115import qualified Streamly.Data.Unfold as UF

116+import qualified Streamly.Internal.Data.Unfold as UF (bracketIO)

116117import qualified Streamly.Internal.Data.Fold.Type as FL

117118 (Step(..), snoc, reduce)

118−import qualified Streamly.Internal.Data.Unfold as UF (bracketIO)

119119import qualified Streamly.Internal.FileSystem.Handle as FH

120120import qualified Streamly.Internal.Data.Stream.Chunked as AS

121121import qualified Streamly.Data.Stream as S (fold, bracketIO, mapM)

src/Streamly/Internal/Network/Inet/TCP.hs+1−1

@@ -120,7 +120,7 @@ import qualified Network.Socket as Net

120120import qualified Streamly.Data.Array as A

121121import qualified Streamly.Data.Fold as FL

122122import qualified Streamly.Data.Unfold as UF

123−import qualified Streamly.Internal.Data.Unfold as UF (bracketIO, first)

123+import qualified Streamly.Internal.Data.Unfold as UF (first, bracketIO)

124124import qualified Streamly.Internal.Data.Stream.Chunked as AS

125125import qualified Streamly.Internal.Data.Fold.Type as FL (Step(..))

126126import qualified Streamly.Internal.Data.Stream as S