7fb7d1b · streamly · git.iko.soy

git.iko.soy/streamly

Improve docs of array modules, pin/unpin ops

commit7fb7d1b77df77ed9e41c95be3ada490d4c7d5cca authorHarendra Kumar <harendra@composewell.com> dateSun 26 Nov 2023, 00:33 (3 years ago) parent13581bf

7 files changed+73−57

compare with master

unifiedsplit

core/src/Streamly/Data/Array.hs+14−5 core/src/Streamly/Data/MutArray.hs+6−6 core/src/Streamly/Internal/Data/Array.hs+3−6 core/src/Streamly/Internal/Data/Array/Type.hs+14−12 core/src/Streamly/Internal/Data/MutArray.hs+4−2 core/src/Streamly/Internal/Data/MutArray/Type.hs+27−26 core/src/Streamly/Internal/Data/MutByteArray/Type.hs+5

core/src/Streamly/Data/Array.hs+14−5

@@ -53,6 +53,19 @@ module Streamly.Data.Array

5353 -- list.

5454 , toList

5555

56+ -- * Pinning & Unpinning

57+ -- | Arrays are created unpinned by default unless pinned versions of

58+ -- creation APIs are used. Look for APIs with @pinned@ prefix in

59+ -- "Streamly.Internal.Data.Array" for some unreleased pinned creation APIs.

60+ -- If an array is to be sent to the OS without any further modification

61+ -- then it should be created pinned in the first place instead of pinning

62+ -- it later. Pinning an unpinned array has a copy overhead. OS interfacing

63+ -- APIs create a pinned array directly or convert an unpinned array to

64+ -- pinned array before sending it to the OS.

65+ , pin

66+ , unpin

67+ , isPinned

68+

5669 -- * Unfolds

5770 , reader

5871 , readerRev

@@ -66,13 +79,9 @@ module Streamly.Data.Array

6679 -- , (!!)

6780 , getIndex

6881

69− -- * Unbox Type Class

82+ -- * Re-exports

7083 , Unbox (..)

7184

72− -- * Pinning & Unpinning

73− , pin

74− , unpin

75− , isPinned

7685 )

7786where

7887

core/src/Streamly/Data/MutArray.hs+6−6

@@ -42,6 +42,11 @@ module Streamly.Data.MutArray

4242 , write -- full buffer

4343 -- writeLastN

4444

45+ -- * Pinning & Unpinning

46+ , pin

47+ , unpin

48+ , isPinned

49+

4550 -- * Appending elements

4651 , snoc

4752

@@ -78,14 +83,9 @@ module Streamly.Data.MutArray

7883 -- * Size

7984 , length

8085

81− -- * Unbox Type Class

86+ -- * Re-exports

8287 , Unbox (..)

8388

84− -- * Pinning & Unpinning

85− , pin

86− , unpin

87− , isPinned

88−

8989 -- * Deprecated

9090 , newPinned

9191 )

core/src/Streamly/Internal/Data/Array.hs+3−6

@@ -27,10 +27,7 @@ module Streamly.Internal.Data.Array

2727 -- Monadic Folds

2828 , writeLastN

2929

30− -- * Elimination

31− -- ** Conversion

32−

33− -- ** Unfolds

30+ -- * Unfolds

3431 , reader

3532 , readerUnsafe

3633 , producer -- experimental

@@ -73,11 +70,11 @@ module Streamly.Internal.Data.Array

7370 -- * Streaming Operations

7471 , streamTransform

7572

76− -- ** Folding

73+ -- * Folding

7774 , streamFold

7875 , fold

7976

80− -- ** Serialization

77+ -- * Serialization

8178 , encodeAs

8279 , serialize

8380 , pinnedSerialize

core/src/Streamly/Internal/Data/Array/Type.hs+14−12

@@ -12,22 +12,23 @@

1212--

1313module Streamly.Internal.Data.Array.Type

1414 (

15+ -- ** Type

1516 -- $arrayNotes

1617 Array (..)

1718 , asPtrUnsafe

1819 , nil

1920

20− -- * Freezing and Thawing

21+ -- ** Freezing and Thawing

2122 , unsafeFreeze

2223 , unsafeFreezeWithShrink

2324 , unsafeThaw

2425

25− -- * Pinning and Unpinning

26+ -- ** Pinning and Unpinning

2627 , pin

2728 , unpin

2829 , isPinned

2930

30− -- * Construction

31+ -- ** Construction

3132 , splice

3233

3334 , fromList

@@ -41,14 +42,14 @@ module Streamly.Internal.Data.Array.Type

4142 , fromPureStream

4243 , fromByteStr#

4344

44− -- * Split

45+ -- ** Split

4546 , breakOn

4647

4748 -- ** Cloning arrays

4849 , clone

4950 , pinnedClone

5051

51− -- * Elimination

52+ -- ** Elimination

5253 , unsafeIndexIO

5354 , getIndexUnsafe

5455 , byteLength

@@ -69,7 +70,7 @@ module Streamly.Internal.Data.Array.Type

6970 , readerRev

7071 , toList

7172

72− -- * Folds

73+ -- ** Folds

7374 , writeWith

7475 , writeN

7576 , pinnedWriteN

@@ -81,14 +82,14 @@ module Streamly.Internal.Data.Array.Type

8182 , pinnedWrite

8283 , unsafeMakePure

8384

84− -- * Streams of arrays

85+ -- ** Streams of arrays

8586 , chunksOf

8687 , pinnedChunksOf

8788 , bufferChunks

8889 , flattenArrays

8990 , flattenArraysRev

9091

91− -- * Deprecated

92+ -- ** Deprecated

9293 , unsafeIndex

9394 )

9495where

@@ -230,18 +231,19 @@ unsafeThaw (Array ac as ae) = MutArray ac as ae ae

230231-- Pinning & Unpinning

231232-------------------------------------------------------------------------------

232233

233−-- | Copy the 'Array' to pinned memory if unpinned, else do nothing. The

234−-- overhead is a copy if the input array is unpinned.

234+-- | Return a copy of the 'Array' in pinned memory if unpinned, else return the

235+-- original array.

235236{-# INLINE pin #-}

236237pin :: Array a -> IO (Array a)

237238pin = fmap unsafeFreeze . MA.pin . unsafeThaw

238239

239−-- | Copy the 'Array' to unpinned memory if pinned, else do nothing. The

240−-- overhead is a copy if the input array is pinned.

240+-- | Return a copy of the 'Array' in unpinned memory if pinned, else return the

241+-- original array.

241242{-# INLINE unpin #-}

242243unpin :: Array a -> IO (Array a)

243244unpin = fmap unsafeFreeze . MA.unpin . unsafeThaw

244245

246+-- | Return 'True' if the array is allocated in pinned memory.

245247{-# INLINE isPinned #-}

246248isPinned :: Array a -> Bool

247249isPinned = MA.isPinned . unsafeThaw

core/src/Streamly/Internal/Data/MutArray.hs+4−2

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

88--

99module Streamly.Internal.Data.MutArray

1010 (

11+ -- * MutArray.Type module

1112 module Streamly.Internal.Data.MutArray.Type

12− -- * Unboxed IORef

13− , module Streamly.Internal.Data.IORef.Unboxed

13+ -- * MutArray module

1414 , splitOn

1515 , genSlicesFromLen

1616 , getSlicesFromLen

1717 , fromStream

18+ -- * Unboxed IORef

19+ , module Streamly.Internal.Data.IORef.Unboxed

1820 )

1921where

2022

core/src/Streamly/Internal/Data/MutArray/Type.hs+27−26

@@ -28,7 +28,7 @@

2828

2929module Streamly.Internal.Data.MutArray.Type

3030 (

31− -- * Type

31+ -- ** Type

3232 -- $arrayNotes

3333 MutArray (..)

3434 , MutByteArray

@@ -37,7 +37,7 @@ module Streamly.Internal.Data.MutArray.Type

3737 , unpin

3838 , isPinned

3939

40− -- * Constructing and Writing

40+ -- -- * Constructing and Writing

4141 -- ** Construction

4242 , nil

4343

@@ -65,7 +65,7 @@ module Streamly.Internal.Data.MutArray.Type

6565 , writeRevN

6666 -- , writeRev

6767

68− -- ** From containers

68+ -- *** From containers

6969 , fromListN

7070 , pinnedFromListN

7171 , fromList

@@ -76,7 +76,7 @@ module Streamly.Internal.Data.MutArray.Type

7676 , fromStreamD

7777 , fromPureStream

7878

79− -- * Random writes

79+ -- ** Random writes

8080 , putIndex

8181 , putIndexUnsafe

8282 , putIndices

@@ -93,32 +93,32 @@ module Streamly.Internal.Data.MutArray.Type

9393 , swapIndices

9494 , unsafeSwapIndices

9595

96− -- * Growing and Shrinking

97− -- Arrays grow only at the end, though it is possible to grow on both sides

96+ -- ** Growing and Shrinking

97+ -- | Arrays grow only at the end, though it is possible to grow on both sides

9898 -- and therefore have a cons as well as snoc. But that will require two

9999 -- bounds in the array representation.

100100

101− -- ** Appending elements

101+ -- *** Appending elements

102102 , snocWith

103103 , snoc

104104 , snocLinear

105105 , snocMay

106106 , snocUnsafe

107107

108− -- ** Appending streams

108+ -- *** Appending streams

109109 , writeAppendNUnsafe

110110 , writeAppendN

111111 , writeAppendWith

112112 , writeAppend

113113

114− -- * Eliminating and Reading

114+ -- ** Eliminating and Reading

115115

116− -- ** To streams

116+ -- *** To streams

117117 , reader

118118 , readerRevWith

119119 , readerRev

120120

121− -- ** To containers

121+ -- *** To containers

122122 , toStreamDWith

123123 , toStreamDRevWith

124124 , toStreamKWith

@@ -133,7 +133,7 @@ module Streamly.Internal.Data.MutArray.Type

133133 , producerWith

134134 , producer

135135

136− -- ** Random reads

136+ -- *** Random reads

137137 , getIndex

138138 , getIndexUnsafe

139139 , getIndices

@@ -141,7 +141,7 @@ module Streamly.Internal.Data.MutArray.Type

141141 -- , getFromThenTo

142142 , getIndexRev

143143

144− -- * Memory Management

144+ -- ** Memory Management

145145 , blockSize

146146 , arrayChunkBytes

147147 , allocBytesToElemCount

@@ -150,14 +150,14 @@ module Streamly.Internal.Data.MutArray.Type

150150 , resizeExp

151151 , rightSize

152152

153− -- * Size

153+ -- ** Size

154154 , length

155155 , byteLength

156156 -- , capacity

157157 , byteCapacity

158158 , bytesFree

159159

160− -- * In-place Mutation Algorithms

160+ -- ** In-place Mutation Algorithms

161161 , strip

162162 , reverse

163163 , permute

@@ -167,18 +167,18 @@ module Streamly.Internal.Data.MutArray.Type

167167 , mergeBy

168168 , bubble

169169

170− -- * Casting

170+ -- ** Casting

171171 , cast

172172 , castUnsafe

173173 , asBytes

174174 , asPtrUnsafe

175175

176− -- * Folding

176+ -- ** Folding

177177 , foldl'

178178 , foldr

179179 , cmp

180180

181− -- * Arrays of arrays

181+ -- ** Arrays of arrays

182182 -- We can add dimensionality parameter to the array type to get

183183 -- multidimensional arrays. Multidimensional arrays would just be a

184184 -- convenience wrapper on top of single dimensional arrays.

@@ -186,17 +186,17 @@ module Streamly.Internal.Data.MutArray.Type

186186 -- | Operations dealing with multiple arrays, streams of arrays or

187187 -- multidimensional array representations.

188188

189− -- ** Construct from streams

189+ -- *** Construct from streams

190190 , chunksOf

191191 , pinnedChunksOf

192192 , writeChunks

193193

194− -- ** Eliminate to streams

194+ -- *** Eliminate to streams

195195 , flattenArrays

196196 , flattenArraysRev

197197 , fromArrayStreamK

198198

199− -- ** Construct from arrays

199+ -- *** Construct from arrays

200200 -- get chunks without copying

201201 , getSliceUnsafe

202202 , getSlice

@@ -218,7 +218,7 @@ module Streamly.Internal.Data.MutArray.Type

218218 -- , appendSlice

219219 -- , appendSliceFrom

220220

221− -- * Utilities

221+ -- ** Utilities

222222 , roundUpToPower2

223223 , memcpy

224224 , memcmp

@@ -357,8 +357,8 @@ data MutArray a =

357357-- Pinning & Unpinning

358358-------------------------------------------------------------------------------

359359

360−-- | Copy the 'MutArray' to pinned memory if unpinned, else do nothing. The

361−-- overhead is a copy if the input array is unpinned.

360+-- | Return a copy of the array in pinned memory if unpinned, else return the

361+-- original array.

362362{-# INLINE pin #-}

363363pin :: MutArray a -> IO (MutArray a)

364364pin arr@MutArray{..} =

@@ -366,8 +366,8 @@ pin arr@MutArray{..} =

366366 then pure arr

367367 else pinnedClone arr

368368

369−-- | Copy the 'MutArray' to unpinned memory if pinned, else do nothing. The

370−-- overhead is a copy if the input array is pinned.

369+-- | Return a copy of the array in unpinned memory if pinned, else return the

370+-- original array.

371371{-# INLINE unpin #-}

372372unpin :: MutArray a -> IO (MutArray a)

373373unpin arr@MutArray{..} =

@@ -375,6 +375,7 @@ unpin arr@MutArray{..} =

375375 then clone arr

376376 else pure arr

377377

378+-- | Return 'True' if the array is allocated in pinned memory.

378379{-# INLINE isPinned #-}

379380isPinned :: MutArray a -> Bool

380381isPinned MutArray{..} = Unboxed.isPinned arrContents

core/src/Streamly/Internal/Data/MutByteArray/Type.hs+5

@@ -194,6 +194,7 @@ putSliceUnsafe src srcStartBytes dst dstStartBytes lenBytes = liftIO $ do

194194-- Pinning & Unpinning

195195-------------------------------------------------------------------------------

196196

197+-- | Return 'True' if the array is allocated in pinned memory.

197198{-# INLINE isPinned #-}

198199isPinned :: MutByteArray -> Bool

199200isPinned (MutByteArray arr#) =

@@ -216,6 +217,8 @@ cloneMutableArrayWith# alloc# arr# s# =

216217 case copyMutableByteArray# arr# 0# arr1# 0# i# s2# of

217218 s3# -> (# s3#, arr1# #)

218219

220+-- | Return a copy of the array in pinned memory if unpinned, else return the

221+-- original array.

219222{-# INLINE pin #-}

220223pin :: MutByteArray -> IO MutByteArray

221224pin arr@(MutByteArray marr#) =

@@ -232,6 +235,8 @@ pin arr@(MutByteArray marr#) =

232235 case cloneMutableArrayWith# newPinnedByteArray# marr# s# of

233236 (# s1#, marr1# #) -> (# s1#, MutByteArray marr1# #)

234237

238+-- | Return a copy of the array in unpinned memory if pinned, else return the

239+-- original array.

235240{-# INLINE unpin #-}

236241unpin :: MutByteArray -> IO MutByteArray

237242unpin arr@(MutByteArray marr#) =