git.iko.soy/streamly
on master help sign in
Improve docs of array modules, pin/unpin ops
7fb7d1bHarendra Kumar
core/src/Streamly/Data/Array.hs+14−5
compare with master
unifiedsplit
@@ -53,6 +53,19 @@ module Streamly.Data.Array
53 -- list.
53 -- list.
54 , toList
54 , toList
55
55
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+
56 -- * Unfolds
69 -- * Unfolds
57 , reader
70 , reader
58 , readerRev
71 , readerRev
@@ -66,13 +79,9 @@ module Streamly.Data.Array
66 -- , (!!)
79 -- , (!!)
67 , getIndex
80 , getIndex
68
81
69− -- * Unbox Type Class
82+ -- * Re-exports
70 , Unbox (..)
83 , Unbox (..)
71
84
72− -- * Pinning & Unpinning
73− , pin
74− , unpin
75− , isPinned
76 )
85 )
77where
86where
78
87
core/src/Streamly/Data/MutArray.hs+6−6
@@ -42,6 +42,11 @@ module Streamly.Data.MutArray
42 , write -- full buffer
42 , write -- full buffer
43 -- writeLastN
43 -- writeLastN
44
44
45+ -- * Pinning & Unpinning
46+ , pin
47+ , unpin
48+ , isPinned
49+
45 -- * Appending elements
50 -- * Appending elements
46 , snoc
51 , snoc
47
52
@@ -78,14 +83,9 @@ module Streamly.Data.MutArray
78 -- * Size
83 -- * Size
79 , length
84 , length
80
85
81− -- * Unbox Type Class
86+ -- * Re-exports
82 , Unbox (..)
87 , Unbox (..)
83
88
84− -- * Pinning & Unpinning
85− , pin
86− , unpin
87− , isPinned
88−
89 -- * Deprecated
89 -- * Deprecated
90 , newPinned
90 , newPinned
91 )
91 )
core/src/Streamly/Internal/Data/Array.hs+3−6
@@ -27,10 +27,7 @@ module Streamly.Internal.Data.Array
27 -- Monadic Folds
27 -- Monadic Folds
28 , writeLastN
28 , writeLastN
29
29
30− -- * Elimination
31− -- ** Conversion
32−
33− -- ** Unfolds
30+ -- * Unfolds
34 , reader
31 , reader
35 , readerUnsafe
32 , readerUnsafe
36 , producer -- experimental
33 , producer -- experimental
@@ -73,11 +70,11 @@ module Streamly.Internal.Data.Array
73 -- * Streaming Operations
70 -- * Streaming Operations
74 , streamTransform
71 , streamTransform
75
72
76− -- ** Folding
73+ -- * Folding
77 , streamFold
74 , streamFold
78 , fold
75 , fold
79
76
80− -- ** Serialization
77+ -- * Serialization
81 , encodeAs
78 , encodeAs
82 , serialize
79 , serialize
83 , pinnedSerialize
80 , pinnedSerialize
core/src/Streamly/Internal/Data/Array/Type.hs+14−12
@@ -12,22 +12,23 @@
12--
12--
13module Streamly.Internal.Data.Array.Type
13module Streamly.Internal.Data.Array.Type
14 (
14 (
15+ -- ** Type
15 -- $arrayNotes
16 -- $arrayNotes
16 Array (..)
17 Array (..)
17 , asPtrUnsafe
18 , asPtrUnsafe
18 , nil
19 , nil
19
20
20− -- * Freezing and Thawing
21+ -- ** Freezing and Thawing
21 , unsafeFreeze
22 , unsafeFreeze
22 , unsafeFreezeWithShrink
23 , unsafeFreezeWithShrink
23 , unsafeThaw
24 , unsafeThaw
24
25
25− -- * Pinning and Unpinning
26+ -- ** Pinning and Unpinning
26 , pin
27 , pin
27 , unpin
28 , unpin
28 , isPinned
29 , isPinned
29
30
30− -- * Construction
31+ -- ** Construction
31 , splice
32 , splice
32
33
33 , fromList
34 , fromList
@@ -41,14 +42,14 @@ module Streamly.Internal.Data.Array.Type
41 , fromPureStream
42 , fromPureStream
42 , fromByteStr#
43 , fromByteStr#
43
44
44− -- * Split
45+ -- ** Split
45 , breakOn
46 , breakOn
46
47
47 -- ** Cloning arrays
48 -- ** Cloning arrays
48 , clone
49 , clone
49 , pinnedClone
50 , pinnedClone
50
51
51− -- * Elimination
52+ -- ** Elimination
52 , unsafeIndexIO
53 , unsafeIndexIO
53 , getIndexUnsafe
54 , getIndexUnsafe
54 , byteLength
55 , byteLength
@@ -69,7 +70,7 @@ module Streamly.Internal.Data.Array.Type
69 , readerRev
70 , readerRev
70 , toList
71 , toList
71
72
72− -- * Folds
73+ -- ** Folds
73 , writeWith
74 , writeWith
74 , writeN
75 , writeN
75 , pinnedWriteN
76 , pinnedWriteN
@@ -81,14 +82,14 @@ module Streamly.Internal.Data.Array.Type
81 , pinnedWrite
82 , pinnedWrite
82 , unsafeMakePure
83 , unsafeMakePure
83
84
84− -- * Streams of arrays
85+ -- ** Streams of arrays
85 , chunksOf
86 , chunksOf
86 , pinnedChunksOf
87 , pinnedChunksOf
87 , bufferChunks
88 , bufferChunks
88 , flattenArrays
89 , flattenArrays
89 , flattenArraysRev
90 , flattenArraysRev
90
91
91− -- * Deprecated
92+ -- ** Deprecated
92 , unsafeIndex
93 , unsafeIndex
93 )
94 )
94where
95where
@@ -230,18 +231,19 @@ unsafeThaw (Array ac as ae) = MutArray ac as ae ae
230-- Pinning & Unpinning
231-- Pinning & Unpinning
231-------------------------------------------------------------------------------
232-------------------------------------------------------------------------------
232
233
233−-- | Copy the 'Array' to pinned memory if unpinned, else do nothing. The
234+-- | Return a copy of the 'Array' in pinned memory if unpinned, else return the
234−-- overhead is a copy if the input array is unpinned.
235+-- original array.
235{-# INLINE pin #-}
236{-# INLINE pin #-}
236pin :: Array a -> IO (Array a)
237pin :: Array a -> IO (Array a)
237pin = fmap unsafeFreeze . MA.pin . unsafeThaw
238pin = fmap unsafeFreeze . MA.pin . unsafeThaw
238
239
239−-- | Copy the 'Array' to unpinned memory if pinned, else do nothing. The
240+-- | Return a copy of the 'Array' in unpinned memory if pinned, else return the
240−-- overhead is a copy if the input array is pinned.
241+-- original array.
241{-# INLINE unpin #-}
242{-# INLINE unpin #-}
242unpin :: Array a -> IO (Array a)
243unpin :: Array a -> IO (Array a)
243unpin = fmap unsafeFreeze . MA.unpin . unsafeThaw
244unpin = fmap unsafeFreeze . MA.unpin . unsafeThaw
244
245
246+-- | Return 'True' if the array is allocated in pinned memory.
245{-# INLINE isPinned #-}
247{-# INLINE isPinned #-}
246isPinned :: Array a -> Bool
248isPinned :: Array a -> Bool
247isPinned = MA.isPinned . unsafeThaw
249isPinned = MA.isPinned . unsafeThaw
core/src/Streamly/Internal/Data/MutArray.hs+4−2
@@ -8,13 +8,15 @@
8--
8--
9module Streamly.Internal.Data.MutArray
9module Streamly.Internal.Data.MutArray
10 (
10 (
11+ -- * MutArray.Type module
11 module Streamly.Internal.Data.MutArray.Type
12 module Streamly.Internal.Data.MutArray.Type
12− -- * Unboxed IORef
13+ -- * MutArray module
13− , module Streamly.Internal.Data.IORef.Unboxed
14 , splitOn
14 , splitOn
15 , genSlicesFromLen
15 , genSlicesFromLen
16 , getSlicesFromLen
16 , getSlicesFromLen
17 , fromStream
17 , fromStream
18+ -- * Unboxed IORef
19+ , module Streamly.Internal.Data.IORef.Unboxed
18 )
20 )
19where
21where
20
22
core/src/Streamly/Internal/Data/MutArray/Type.hs+27−26
@@ -28,7 +28,7 @@
28
28
29module Streamly.Internal.Data.MutArray.Type
29module Streamly.Internal.Data.MutArray.Type
30 (
30 (
31− -- * Type
31+ -- ** Type
32 -- $arrayNotes
32 -- $arrayNotes
33 MutArray (..)
33 MutArray (..)
34 , MutByteArray
34 , MutByteArray
@@ -37,7 +37,7 @@ module Streamly.Internal.Data.MutArray.Type
37 , unpin
37 , unpin
38 , isPinned
38 , isPinned
39
39
40− -- * Constructing and Writing
40+ -- -- * Constructing and Writing
41 -- ** Construction
41 -- ** Construction
42 , nil
42 , nil
43
43
@@ -65,7 +65,7 @@ module Streamly.Internal.Data.MutArray.Type
65 , writeRevN
65 , writeRevN
66 -- , writeRev
66 -- , writeRev
67
67
68− -- ** From containers
68+ -- *** From containers
69 , fromListN
69 , fromListN
70 , pinnedFromListN
70 , pinnedFromListN
71 , fromList
71 , fromList
@@ -76,7 +76,7 @@ module Streamly.Internal.Data.MutArray.Type
76 , fromStreamD
76 , fromStreamD
77 , fromPureStream
77 , fromPureStream
78
78
79− -- * Random writes
79+ -- ** Random writes
80 , putIndex
80 , putIndex
81 , putIndexUnsafe
81 , putIndexUnsafe
82 , putIndices
82 , putIndices
@@ -93,32 +93,32 @@ module Streamly.Internal.Data.MutArray.Type
93 , swapIndices
93 , swapIndices
94 , unsafeSwapIndices
94 , unsafeSwapIndices
95
95
96− -- * Growing and Shrinking
96+ -- ** Growing and Shrinking
97− -- Arrays grow only at the end, though it is possible to grow on both sides
97+ -- | Arrays grow only at the end, though it is possible to grow on both sides
98 -- and therefore have a cons as well as snoc. But that will require two
98 -- and therefore have a cons as well as snoc. But that will require two
99 -- bounds in the array representation.
99 -- bounds in the array representation.
100
100
101− -- ** Appending elements
101+ -- *** Appending elements
102 , snocWith
102 , snocWith
103 , snoc
103 , snoc
104 , snocLinear
104 , snocLinear
105 , snocMay
105 , snocMay
106 , snocUnsafe
106 , snocUnsafe
107
107
108− -- ** Appending streams
108+ -- *** Appending streams
109 , writeAppendNUnsafe
109 , writeAppendNUnsafe
110 , writeAppendN
110 , writeAppendN
111 , writeAppendWith
111 , writeAppendWith
112 , writeAppend
112 , writeAppend
113
113
114− -- * Eliminating and Reading
114+ -- ** Eliminating and Reading
115
115
116− -- ** To streams
116+ -- *** To streams
117 , reader
117 , reader
118 , readerRevWith
118 , readerRevWith
119 , readerRev
119 , readerRev
120
120
121− -- ** To containers
121+ -- *** To containers
122 , toStreamDWith
122 , toStreamDWith
123 , toStreamDRevWith
123 , toStreamDRevWith
124 , toStreamKWith
124 , toStreamKWith
@@ -133,7 +133,7 @@ module Streamly.Internal.Data.MutArray.Type
133 , producerWith
133 , producerWith
134 , producer
134 , producer
135
135
136− -- ** Random reads
136+ -- *** Random reads
137 , getIndex
137 , getIndex
138 , getIndexUnsafe
138 , getIndexUnsafe
139 , getIndices
139 , getIndices
@@ -141,7 +141,7 @@ module Streamly.Internal.Data.MutArray.Type
141 -- , getFromThenTo
141 -- , getFromThenTo
142 , getIndexRev
142 , getIndexRev
143
143
144− -- * Memory Management
144+ -- ** Memory Management
145 , blockSize
145 , blockSize
146 , arrayChunkBytes
146 , arrayChunkBytes
147 , allocBytesToElemCount
147 , allocBytesToElemCount
@@ -150,14 +150,14 @@ module Streamly.Internal.Data.MutArray.Type
150 , resizeExp
150 , resizeExp
151 , rightSize
151 , rightSize
152
152
153− -- * Size
153+ -- ** Size
154 , length
154 , length
155 , byteLength
155 , byteLength
156 -- , capacity
156 -- , capacity
157 , byteCapacity
157 , byteCapacity
158 , bytesFree
158 , bytesFree
159
159
160− -- * In-place Mutation Algorithms
160+ -- ** In-place Mutation Algorithms
161 , strip
161 , strip
162 , reverse
162 , reverse
163 , permute
163 , permute
@@ -167,18 +167,18 @@ module Streamly.Internal.Data.MutArray.Type
167 , mergeBy
167 , mergeBy
168 , bubble
168 , bubble
169
169
170− -- * Casting
170+ -- ** Casting
171 , cast
171 , cast
172 , castUnsafe
172 , castUnsafe
173 , asBytes
173 , asBytes
174 , asPtrUnsafe
174 , asPtrUnsafe
175
175
176− -- * Folding
176+ -- ** Folding
177 , foldl'
177 , foldl'
178 , foldr
178 , foldr
179 , cmp
179 , cmp
180
180
181− -- * Arrays of arrays
181+ -- ** Arrays of arrays
182 -- We can add dimensionality parameter to the array type to get
182 -- We can add dimensionality parameter to the array type to get
183 -- multidimensional arrays. Multidimensional arrays would just be a
183 -- multidimensional arrays. Multidimensional arrays would just be a
184 -- convenience wrapper on top of single dimensional arrays.
184 -- convenience wrapper on top of single dimensional arrays.
@@ -186,17 +186,17 @@ module Streamly.Internal.Data.MutArray.Type
186 -- | Operations dealing with multiple arrays, streams of arrays or
186 -- | Operations dealing with multiple arrays, streams of arrays or
187 -- multidimensional array representations.
187 -- multidimensional array representations.
188
188
189− -- ** Construct from streams
189+ -- *** Construct from streams
190 , chunksOf
190 , chunksOf
191 , pinnedChunksOf
191 , pinnedChunksOf
192 , writeChunks
192 , writeChunks
193
193
194− -- ** Eliminate to streams
194+ -- *** Eliminate to streams
195 , flattenArrays
195 , flattenArrays
196 , flattenArraysRev
196 , flattenArraysRev
197 , fromArrayStreamK
197 , fromArrayStreamK
198
198
199− -- ** Construct from arrays
199+ -- *** Construct from arrays
200 -- get chunks without copying
200 -- get chunks without copying
201 , getSliceUnsafe
201 , getSliceUnsafe
202 , getSlice
202 , getSlice
@@ -218,7 +218,7 @@ module Streamly.Internal.Data.MutArray.Type
218 -- , appendSlice
218 -- , appendSlice
219 -- , appendSliceFrom
219 -- , appendSliceFrom
220
220
221− -- * Utilities
221+ -- ** Utilities
222 , roundUpToPower2
222 , roundUpToPower2
223 , memcpy
223 , memcpy
224 , memcmp
224 , memcmp
@@ -357,8 +357,8 @@ data MutArray a =
357-- Pinning & Unpinning
357-- Pinning & Unpinning
358-------------------------------------------------------------------------------
358-------------------------------------------------------------------------------
359
359
360−-- | Copy the 'MutArray' to pinned memory if unpinned, else do nothing. The
360+-- | Return a copy of the array in pinned memory if unpinned, else return the
361−-- overhead is a copy if the input array is unpinned.
361+-- original array.
362{-# INLINE pin #-}
362{-# INLINE pin #-}
363pin :: MutArray a -> IO (MutArray a)
363pin :: MutArray a -> IO (MutArray a)
364pin arr@MutArray{..} =
364pin arr@MutArray{..} =
@@ -366,8 +366,8 @@ pin arr@MutArray{..} =
366 then pure arr
366 then pure arr
367 else pinnedClone arr
367 else pinnedClone arr
368
368
369−-- | Copy the 'MutArray' to unpinned memory if pinned, else do nothing. The
369+-- | Return a copy of the array in unpinned memory if pinned, else return the
370−-- overhead is a copy if the input array is pinned.
370+-- original array.
371{-# INLINE unpin #-}
371{-# INLINE unpin #-}
372unpin :: MutArray a -> IO (MutArray a)
372unpin :: MutArray a -> IO (MutArray a)
373unpin arr@MutArray{..} =
373unpin arr@MutArray{..} =
@@ -375,6 +375,7 @@ unpin arr@MutArray{..} =
375 then clone arr
375 then clone arr
376 else pure arr
376 else pure arr
377
377
378+-- | Return 'True' if the array is allocated in pinned memory.
378{-# INLINE isPinned #-}
379{-# INLINE isPinned #-}
379isPinned :: MutArray a -> Bool
380isPinned :: MutArray a -> Bool
380isPinned MutArray{..} = Unboxed.isPinned arrContents
381isPinned 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
194-- Pinning & Unpinning
194-- Pinning & Unpinning
195-------------------------------------------------------------------------------
195-------------------------------------------------------------------------------
196
196
197+-- | Return 'True' if the array is allocated in pinned memory.
197{-# INLINE isPinned #-}
198{-# INLINE isPinned #-}
198isPinned :: MutByteArray -> Bool
199isPinned :: MutByteArray -> Bool
199isPinned (MutByteArray arr#) =
200isPinned (MutByteArray arr#) =
@@ -216,6 +217,8 @@ cloneMutableArrayWith# alloc# arr# s# =
216 case copyMutableByteArray# arr# 0# arr1# 0# i# s2# of
217 case copyMutableByteArray# arr# 0# arr1# 0# i# s2# of
217 s3# -> (# s3#, arr1# #)
218 s3# -> (# s3#, arr1# #)
218
219
220+-- | Return a copy of the array in pinned memory if unpinned, else return the
221+-- original array.
219{-# INLINE pin #-}
222{-# INLINE pin #-}
220pin :: MutByteArray -> IO MutByteArray
223pin :: MutByteArray -> IO MutByteArray
221pin arr@(MutByteArray marr#) =
224pin arr@(MutByteArray marr#) =
@@ -232,6 +235,8 @@ pin arr@(MutByteArray marr#) =
232 case cloneMutableArrayWith# newPinnedByteArray# marr# s# of
235 case cloneMutableArrayWith# newPinnedByteArray# marr# s# of
233 (# s1#, marr1# #) -> (# s1#, MutByteArray marr1# #)
236 (# s1#, marr1# #) -> (# s1#, MutByteArray marr1# #)
234
237
238+-- | Return a copy of the array in unpinned memory if pinned, else return the
239+-- original array.
235{-# INLINE unpin #-}
240{-# INLINE unpin #-}
236unpin :: MutByteArray -> IO MutByteArray
241unpin :: MutByteArray -> IO MutByteArray
237unpin arr@(MutByteArray marr#) =
242unpin arr@(MutByteArray marr#) =