@@ -40,22 +40,22 @@ module Streamly.Internal.Data.MutArray.Type
4040
4141 -- ** Casting
4242 , cast
43− , castUnsafe
43+ , castUnsafe -- XXX unsafeCast
4444 , asBytes
45− , asPtrUnsafe
46− , asUnpinnedPtrUnsafe
45+ , unsafePinnedAsPtr
46+ , unsafeAsPtr
4747
4848 -- ** Construction
49− , nil
49+ , empty
5050
5151 -- *** New
5252 -- | New arrays are always empty arrays with some reserve capacity to
5353 -- extend the length without reallocating.
54− , new
55− , newArrayWith
56− , pinnedNew
57− , pinnedNewBytes
58− , pinnedNewAligned
54+ , emptyOf
55+ , newArrayWith -- emptyAlignedWith
56+ , pinnedEmptyOf
57+ , pinnedNewAligned -- XXX not required
58+ -- , new -- uninitialized array of specified length
5959
6060 -- *** Cloning
6161 , clone
@@ -63,27 +63,25 @@ module Streamly.Internal.Data.MutArray.Type
6363
6464 -- *** Slicing
6565 -- | Get a subarray without copying
66− , getSliceUnsafe
66+ , getSliceUnsafe -- XXX unsafeGetSlice
6767 , getSlice
6868 , splitAt -- XXX should be able to express using getSlice
6969 , breakOn
7070
7171 -- *** Stream Folds
7272 , ArrayUnsafe (..)
73− , writeNWithUnsafe
74− , writeNWith
75− , writeNUnsafe
76− , pinnedWriteNUnsafe
77− , writeN
78− , pinnedWriteN
79− , pinnedWriteNAligned
80−
81− , writeWith
82− , write
83− , pinnedWrite
84−
85− , writeRevN
86− -- , writeRev
73+ , unsafeCreateOfWith
74+ , unsafeCreateOf
75+ , unsafePinnedCreateOf
76+ , pinnedCreateOf
77+ , createOfWith
78+ , createOf
79+ , revCreateOf
80+
81+ , pinnedCreate
82+ , createWith
83+ , create
84+ -- , revCreate
8785
8886 -- *** From containers
8987 , fromListN
@@ -99,11 +97,11 @@ module Streamly.Internal.Data.MutArray.Type
9997 , fromByteStr#
10098 , fromPtrN
10199 , fromChunksK
102− , fromChunksRealloced
100+ , fromChunksRealloced -- fromSmallChunks
103101
104102 -- ** Random writes
105103 , putIndex
106− , putIndexUnsafe
104+ , putIndexUnsafe -- XXX unsafePutIndex
107105 , putIndices
108106 -- , putFromThenTo
109107 -- , putFrom -- start writing at the given position
@@ -111,7 +109,7 @@ module Streamly.Internal.Data.MutArray.Type
111109 -- , putFromTo
112110 -- , putFromRev
113111 -- , putUptoRev
114− , modifyIndexUnsafe
112+ , modifyIndexUnsafe -- XXX unsafeModifyIndex
115113 , modifyIndex
116114 , modifyIndices
117115 , modify
@@ -122,9 +120,9 @@ module Streamly.Internal.Data.MutArray.Type
122120
123121 -- *** Indexing
124122 , getIndex
125− , getIndexUnsafe
123+ , getIndexUnsafe -- XXX unsafeGetIndex
126124 -- , getFromThenTo
127− , getIndexRev
125+ , getIndexRev -- getRevIndex?
128126 , indexReader
129127 , indexReaderWith
130128
@@ -195,20 +193,20 @@ module Streamly.Internal.Data.MutArray.Type
195193 , snoc
196194 , snocLinear
197195 , snocMay
198− , snocUnsafe
196+ , snocUnsafe -- XXX unsafeSnoc
199197
200198 -- *** Appending streams
201− , writeAppendNUnsafe
202− , writeAppendN
203− , writeAppendWith
204− , writeAppend
199+ , unsafeAppendN
200+ , appendN
201+ , appendWith
202+ , append
205203
206204 -- *** Appending arrays
207205 , spliceCopy
208206 , spliceWith
209207 , splice
210208 , spliceExp
211− , spliceUnsafe
209+ , spliceUnsafe -- XXX unsafeSplice
212210 -- , putSlice
213211 -- , appendSlice
214212 -- , appendSliceFrom
@@ -216,12 +214,12 @@ module Streamly.Internal.Data.MutArray.Type
216214 -- ** Serialization using Unbox
217215 , pokeAppend
218216 , pokeAppendMay
219− , pokeSkipUnsafe
217+ , pokeSkipUnsafe -- unsafePokeSkip
220218
221219 -- ** Deserialization using Unbox
222220 , peekUncons
223− , peekUnconsUnsafe
224− , peekSkipUnsafe
221+ , peekUnconsUnsafe -- unsafePeekUncons
222+ , peekSkipUnsafe -- unsafePeekSkip
225223
226224 -- Arrays of arrays
227225 -- We can add dimensionality parameter to the array type to get
@@ -244,6 +242,8 @@ module Streamly.Internal.Data.MutArray.Type
244242
245243 -- *** Concat
246244 -- | Append the arrays in a stream to form a stream of elements.
245+ , concatWith
246+ , concatRevWith
247247 , concat
248248 , concatRev
249249
@@ -251,9 +251,12 @@ module Streamly.Internal.Data.MutArray.Type
251251 -- | Append the arrays in a stream to form a stream of larger arrays.
252252 , SpliceState (..)
253253 , pCompactLE
254− , rCompactLE
254+ , pPinnedCompactLE
255+ , compactLeAs
255256 , fCompactGE
257+ , fPinnedCompactGE
256258 , lCompactGE
259+ , lPinnedCompactGE
257260 , compactGE
258261 , compactEQ
259262
@@ -264,6 +267,7 @@ module Streamly.Internal.Data.MutArray.Type
264267 , c_memchr
265268
266269 -- * Deprecated
270+ , asPtrUnsafe
267271 , writeChunks
268272 , flattenArrays
269273 , flattenArraysRev
@@ -275,6 +279,25 @@ module Streamly.Internal.Data.MutArray.Type
275279 , getIndicesWith
276280 , resize
277281 , resizeExp
282+ , nil
283+ , new
284+ , pinnedNew
285+ , pinnedNewBytes
286+ , writeAppendNUnsafe
287+ , writeAppendN
288+ , writeAppendWith
289+ , writeAppend
290+ , writeNWithUnsafe
291+ , writeNWith
292+ , writeNUnsafe
293+ , pinnedWriteNUnsafe
294+ , writeN
295+ , pinnedWriteN
296+ , pinnedWriteNAligned -- XXX not required
297+ , writeWith
298+ , write
299+ , pinnedWrite
300+ , writeRevN
278301 )
279302where
280303
@@ -456,6 +479,8 @@ isPinned MutArray{..} = Unboxed.isPinned arrContents
456479-- we need more than that. See stg_pinnedNewAlignedByteArrayzh and
457480-- allocatePinned in GHC source.
458481
482+-- XXX Rename to emptyAlignedWith, alignSize should be first arg.
483+
459484-- | @newArrayWith allocator alignment count@ allocates a new array of zero
460485-- length and with a capacity to hold @count@ elements, using @allocator
461486-- size alignment@ as the memory allocator function.
@@ -479,12 +504,25 @@ newArrayWith alloc alignSize count = do
479504 , arrBound = size
480505 }
481506
507+-- For arrays "nil" sounds a bit odd. empty is better. The only problem with
508+-- empty is that it is also used by the Alternative type class. But assuming we
509+-- will mostly import the Array module qualified this should be fine.
510+
511+-- | Create an empty array.
512+empty ::
513+#ifdef DEVBUILD
514+ Unbox a =>
515+#endif
516+ MutArray a
517+empty = MutArray Unboxed.empty 0 0 0
518+
519+{-# DEPRECATED nil "Please use empty instead." #-}
482520nil ::
483521#ifdef DEVBUILD
484522 Unbox a =>
485523#endif
486524 MutArray a
487−nil = MutArray Unboxed.nil 0 0 0
525+nil = empty
488526
489527{-# INLINE newBytesAs #-}
490528newBytesAs :: MonadIO m =>
@@ -507,6 +545,7 @@ newBytesAs ps bytes = do
507545--
508546-- /Pre-release/
509547{-# INLINE pinnedNewBytes #-}
548+{-# DEPRECATED pinnedNewBytes "Please use pinnedEmptyOf with appropriate calculation" #-}
510549pinnedNewBytes :: MonadIO m =>
511550#ifdef DEVBUILD
512551 Unbox a =>
@@ -531,21 +570,31 @@ newAs ps =
531570 (error "new: alignment is not used in unpinned arrays.")
532571
533572-- XXX can unaligned allocation be more efficient when alignment is not needed?
534−--
535−-- | Allocates an empty pinned array that can hold 'count' items. The memory of
536−-- the array is uninitialized and the allocation is aligned as per the 'Unboxed'
537−-- instance of the type.
538−--
573+
574+-- | Allocates a pinned array of zero length but growable to the specified
575+-- capacity without reallocation.
576+{-# INLINE pinnedEmptyOf #-}
577+pinnedEmptyOf :: forall m a. (MonadIO m, Unbox a) => Int -> m (MutArray a)
578+pinnedEmptyOf = newAs Pinned
579+
580+-- XXX Deprecate in major
581+-- {-# DEPRECATED pinnedNew "Please use pinnedEmptyOf instead." #-}
539582{-# INLINE pinnedNew #-}
540583pinnedNew :: forall m a. (MonadIO m, Unbox a) => Int -> m (MutArray a)
541−pinnedNew = newAs Pinned
584+pinnedNew = pinnedEmptyOf
542585
543−-- | Allocates an empty unpinned array that can hold 'count' items. The memory
544−-- of the array is uninitialized.
586+-- | Allocates an unpinned array of zero length but growable to the specified
587+-- capacity without reallocation.
545588--
589+{-# INLINE emptyOf #-}
590+emptyOf :: (MonadIO m, Unbox a) => Int -> m (MutArray a)
591+emptyOf = newAs Unpinned
592+
593+-- XXX Deprecate in major
594+-- {-# DEPRECATED new "Please use emptyOf instead." #-}
546595{-# INLINE new #-}
547596new :: (MonadIO m, Unbox a) => Int -> m (MutArray a)
548−new = newAs Unpinned
597+new = emptyOf
549598
550599-------------------------------------------------------------------------------
551600-- Random writes
@@ -793,15 +842,15 @@ roundDownTo elemSize size = size - (size `mod` elemSize)
793842-- Since this is not inlined Unboxed consrraint leads to dictionary passing
794843-- which complicates some inspection tests.
795844--
796−{-# NOINLINE reallocExplicit #-}
797−reallocExplicit :: Int -> Int -> MutArray a -> IO (MutArray a)
798−reallocExplicit elemSize newCapacityInBytes MutArray{..} = do
845+{-# NOINLINE reallocExplicitAs #-}
846+reallocExplicitAs :: PinnedState -> Int -> Int -> MutArray a -> IO (MutArray a)
847+reallocExplicitAs ps elemSize newCapacityInBytes MutArray{..} = do
799848 assertM(arrEnd <= arrBound)
800849
801850 -- Allocate new array
802851 let newCapMaxInBytes = roundUpLargeArray newCapacityInBytes
803852 contents <-
804− if Unboxed.isPinned arrContents
853+ if ps == Pinned
805854 then Unboxed.pinnedNew newCapMaxInBytes
806855 else Unboxed.new newCapMaxInBytes
807856 let !(MutByteArray mbarrFrom#) = arrContents
@@ -841,7 +890,12 @@ reallocExplicit elemSize newCapacityInBytes MutArray{..} = do
841890-- If the original array is pinned, the newly allocated array is also pinned.
842891{-# INLINABLE realloc #-}
843892realloc :: forall m a. (MonadIO m, Unbox a) => Int -> MutArray a -> m (MutArray a)
844−realloc bytes arr = liftIO $ reallocExplicit (SIZE_OF(a)) bytes arr
893+realloc bytes arr =
894+ let ps =
895+ if isPinned arr
896+ then Pinned
897+ else Unpinned
898+ in liftIO $ reallocExplicitAs ps (SIZE_OF(a)) bytes arr
845899
846900-- | @reallocWith label capSizer minIncrBytes array@. The label is used
847901-- in error messages and the capSizer is used to determine the capacity of the
@@ -890,6 +944,7 @@ grow nElems arr@MutArray{..} = do
890944 else realloc req arr
891945
892946{-# DEPRECATED resize "Please use grow instead." #-}
947+{-# INLINE resize #-}
893948resize :: forall m a. (MonadIO m, Unbox a) =>
894949 Int -> MutArray a -> m (MutArray a)
895950resize = grow
@@ -913,6 +968,7 @@ growExp nElems arr@MutArray{..} = do
913968 else realloc req1 arr
914969
915970{-# DEPRECATED resizeExp "Please use growExp instead." #-}
971+{-# INLINE resizeExp #-}
916972resizeExp :: forall m a. (MonadIO m, Unbox a) =>
917973 Int -> MutArray a -> m (MutArray a)
918974resizeExp = growExp
@@ -1246,6 +1302,7 @@ indexReaderWith liftio (D.Stream stepi sti) = Unfold step inject
12461302 D.Stop -> return D.Stop
12471303
12481304{-# DEPRECATED getIndicesWith "Please use indexReaderWith instead." #-}
1305+{-# INLINE getIndicesWith #-}
12491306getIndicesWith :: (Monad m, Unbox a) =>
12501307 (forall b. IO b -> m b) -> D.Stream m Int -> Unfold m (MutArray a) a
12511308getIndicesWith = indexReaderWith
@@ -1261,6 +1318,7 @@ indexReader = indexReaderWith liftIO
12611318
12621319-- XXX DO NOT REMOVE, change the signature to use Stream instead of unfold
12631320{-# DEPRECATED getIndices "Please use indexReader instead." #-}
1321+{-# INLINE getIndices #-}
12641322getIndices :: (MonadIO m, Unbox a) => Stream m Int -> Unfold m (MutArray a) a
12651323getIndices = indexReader
12661324
@@ -1557,7 +1615,7 @@ chunksOfAs ps n (D.Stream step state) =
15571615--
15581616-- Same as the following but may be more efficient:
15591617--
1560−-- >>> chunksOf n = Stream.foldMany (MutArray.writeN n)
1618+-- >>> chunksOf n = Stream.foldMany (MutArray.createOf n)
15611619--
15621620-- /Pre-release/
15631621{-# INLINE_NORMAL chunksOf #-}
@@ -1566,14 +1624,14 @@ chunksOf :: forall m a. (MonadIO m, Unbox a)
15661624-- XXX the idiomatic implementation leads to large regression in the D.reverse'
15671625-- benchmark. It seems it has difficulty producing optimized code when
15681626-- converting to StreamK. Investigate GHC optimizations.
1569−-- chunksOf n = D.foldMany (writeN n)
1627+-- chunksOf n = D.foldMany (createOf n)
15701628chunksOf = chunksOfAs Unpinned
15711629
15721630-- | Like 'chunksOf' but creates pinned arrays.
15731631{-# INLINE_NORMAL pinnedChunksOf #-}
15741632pinnedChunksOf :: forall m a. (MonadIO m, Unbox a)
15751633 => Int -> D.Stream m a -> D.Stream m (MutArray a)
1576−-- pinnedChunksOf n = D.foldMany (pinnedWriteN n)
1634+-- pinnedChunksOf n = D.foldMany (pinnedCreateOf n)
15771635pinnedChunksOf = chunksOfAs Pinned
15781636
15791637-- | When we are buffering a stream of unknown size into an array we do not
@@ -1606,16 +1664,10 @@ data FlattenState s contents a =
16061664 OuterLoop s
16071665 | InnerLoop s contents !Int !Int
16081666
1609−-- | Use the "reader" unfold instead.
1610−--
1611−-- @concat = unfoldMany reader@
1612−--
1613−-- We can try this if there are any fusion issues in the unfold.
1614−--
1615−{-# INLINE_NORMAL concat #-}
1616−concat :: forall m a. (MonadIO m, Unbox a)
1617− => D.Stream m (MutArray a) -> D.Stream m a
1618−concat (D.Stream step state) = D.Stream step' (OuterLoop state)
1667+{-# INLINE_NORMAL concatWith #-}
1668+concatWith :: forall m a. (Monad m, Unbox a)
1669+ => (forall b. IO b -> m b) -> D.Stream m (MutArray a) -> D.Stream m a
1670+concatWith liftio (D.Stream step state) = D.Stream step' (OuterLoop state)
16191671
16201672 where
16211673
@@ -1632,24 +1684,30 @@ concat (D.Stream step state) = D.Stream step' (OuterLoop state)
16321684 return $ D.Skip $ OuterLoop st
16331685
16341686 step' _ (InnerLoop st contents p end) = do
1635− x <- liftIO $ peekAt p contents
1687+ x <- liftio $ peekAt p contents
16361688 return $ D.Yield x (InnerLoop st contents (INDEX_NEXT(p,a)) end)
16371689
1638−{-# DEPRECATED flattenArrays "Please use \"unfoldMany reader\" instead." #-}
1639−flattenArrays :: forall m a. (MonadIO m, Unbox a)
1640− => D.Stream m (MutArray a) -> D.Stream m a
1641−flattenArrays = concat
1642−
1643−-- | Use the "readerRev" unfold instead.
1690+-- | Use the "reader" unfold instead.
16441691--
1645−-- @concat = unfoldMany readerRev@
1692+-- @concat = unfoldMany reader@
16461693--
16471694-- We can try this if there are any fusion issues in the unfold.
16481695--
1649−{-# INLINE_NORMAL concatRev #-}
1650−concatRev :: forall m a. (MonadIO m, Unbox a)
1696+{-# INLINE_NORMAL concat #-}
1697+concat :: forall m a. (MonadIO m, Unbox a)
1698+ => D.Stream m (MutArray a) -> D.Stream m a
1699+concat = concatWith liftIO
1700+
1701+{-# DEPRECATED flattenArrays "Please use \"unfoldMany reader\" instead." #-}
1702+{-# INLINE flattenArrays #-}
1703+flattenArrays :: forall m a. (MonadIO m, Unbox a)
16511704 => D.Stream m (MutArray a) -> D.Stream m a
1652−concatRev (D.Stream step state) = D.Stream step' (OuterLoop state)
1705+flattenArrays = concat
1706+
1707+{-# INLINE_NORMAL concatRevWith #-}
1708+concatRevWith :: forall m a. (Monad m, Unbox a)
1709+ => (forall b. IO b -> m b) -> D.Stream m (MutArray a) -> D.Stream m a
1710+concatRevWith liftio (D.Stream step state) = D.Stream step' (OuterLoop state)
16531711
16541712 where
16551713
@@ -1667,11 +1725,23 @@ concatRev (D.Stream step state) = D.Stream step' (OuterLoop state)
16671725 return $ D.Skip $ OuterLoop st
16681726
16691727 step' _ (InnerLoop st contents p start) = do
1670− x <- liftIO $ peekAt p contents
1728+ x <- liftio $ peekAt p contents
16711729 let cur = INDEX_PREV(p,a)
16721730 return $ D.Yield x (InnerLoop st contents cur start)
16731731
1732+-- | Use the "readerRev" unfold instead.
1733+--
1734+-- @concat = unfoldMany readerRev@
1735+--
1736+-- We can try this if there are any fusion issues in the unfold.
1737+--
1738+{-# INLINE_NORMAL concatRev #-}
1739+concatRev :: forall m a. (MonadIO m, Unbox a)
1740+ => D.Stream m (MutArray a) -> D.Stream m a
1741+concatRev = concatRevWith liftIO
1742+
16741743{-# DEPRECATED flattenArraysRev "Please use \"unfoldMany readerRev\" instead." #-}
1744+{-# INLINE flattenArraysRev #-}
16751745flattenArraysRev :: forall m a. (MonadIO m, Unbox a)
16761746 => D.Stream m (MutArray a) -> D.Stream m a
16771747flattenArraysRev = concatRev
@@ -1903,7 +1973,7 @@ foldr f z arr = D.foldr f z $ read arr
19031973
19041974-- XXX Keep the bound intact to not lose any free space? Perf impact?
19051975
1906−-- | @writeAppendNUnsafe n arr@ appends up to @n@ input items to the supplied
1976+-- | @unsafeAppendN n arr@ appends up to @n@ input items to the supplied
19071977-- array.
19081978--
19091979-- Unsafe: Do not drive the fold beyond @n@ elements, it will lead to memory
@@ -1912,13 +1982,12 @@ foldr f z arr = D.foldr f z $ read arr
19121982-- Any free space left in the array after appending @n@ elements is lost.
19131983--
19141984-- /Internal/
1915−{-# INLINE_NORMAL writeAppendNUnsafe #-}
1916−writeAppendNUnsafe :: forall m a. (MonadIO m, Unbox a) =>
1985+{-# INLINE_NORMAL unsafeAppendN #-}
1986+unsafeAppendN :: forall m a. (MonadIO m, Unbox a) =>
19171987 Int
19181988 -> m (MutArray a)
19191989 -> Fold m a (MutArray a)
1920−writeAppendNUnsafe n action =
1921− fmap fromArrayUnsafe $ FL.foldlM' step initial
1990+unsafeAppendN n action = fmap fromArrayUnsafe $ FL.foldlM' step initial
19221991
19231992 where
19241993
@@ -1931,7 +2000,7 @@ writeAppendNUnsafe n action =
19312000 -- otherwise we lose that space.
19322001 arr1 <-
19332002 if free < needed
1934− then noinline reallocWith "writeAppendNUnsafeWith" (+ needed) needed arr
2003+ then noinline reallocWith "unsafeAppendN" (+ needed) needed arr
19352004 else return arr
19362005 return $ toArrayUnsafe arr1
19372006
@@ -1939,30 +2008,51 @@ writeAppendNUnsafe n action =
19392008 liftIO $ pokeAt end contents x
19402009 return $ ArrayUnsafe contents start (INDEX_NEXT(end,a))
19412010
2011+{-# DEPRECATED writeAppendNUnsafe "Please use unsafeAppendN instead." #-}
2012+{-# INLINE writeAppendNUnsafe #-}
2013+writeAppendNUnsafe :: forall m a. (MonadIO m, Unbox a) =>
2014+ Int
2015+ -> m (MutArray a)
2016+ -> Fold m a (MutArray a)
2017+writeAppendNUnsafe = unsafeAppendN
2018+
19422019-- | Append @n@ elements to an existing array. Any free space left in the array
19432020-- after appending @n@ elements is lost.
19442021--
1945−-- >>> writeAppendN n initial = Fold.take n (MutArray.writeAppendNUnsafe n initial)
2022+-- >>> appendN n initial = Fold.take n (MutArray.unsafeAppendN n initial)
19462023--
1947−{-# INLINE_NORMAL writeAppendN #-}
2024+{-# INLINE_NORMAL appendN #-}
2025+appendN :: forall m a. (MonadIO m, Unbox a) =>
2026+ Int -> m (MutArray a) -> Fold m a (MutArray a)
2027+appendN n initial = FL.take n (unsafeAppendN n initial)
2028+
2029+-- XXX Deprecate in major
2030+-- {-# DEPRECATED writeAppendN "Please use appendN instead." #-}
2031+{-# INLINE writeAppendN #-}
19482032writeAppendN :: forall m a. (MonadIO m, Unbox a) =>
19492033 Int -> m (MutArray a) -> Fold m a (MutArray a)
1950−writeAppendN n initial = FL.take n (writeAppendNUnsafe n initial)
2034+writeAppendN = appendN
19512035
1952−-- | @writeAppendWith realloc action@ mutates the array generated by @action@ to
2036+-- | @appendWith realloc action@ mutates the array generated by @action@ to
19532037-- append the input stream. If there is no reserved space available in the
19542038-- array it is reallocated to a size in bytes determined by @realloc oldSize@,
19552039-- where @oldSize@ is the current size of the array in bytes.
19562040--
19572041-- Note that the returned array may be a mutated version of original array.
19582042--
1959−-- >>> writeAppendWith sizer = Fold.foldlM' (MutArray.snocWith sizer)
2043+-- >>> appendWith sizer = Fold.foldlM' (MutArray.snocWith sizer)
19602044--
19612045-- /Pre-release/
2046+{-# INLINE appendWith #-}
2047+appendWith :: forall m a. (MonadIO m, Unbox a) =>
2048+ (Int -> Int) -> m (MutArray a) -> Fold m a (MutArray a)
2049+appendWith sizer = FL.foldlM' (snocWith sizer)
2050+
2051+{-# DEPRECATED writeAppendWith "Please use appendWith instead." #-}
19622052{-# INLINE writeAppendWith #-}
19632053writeAppendWith :: forall m a. (MonadIO m, Unbox a) =>
19642054 (Int -> Int) -> m (MutArray a) -> Fold m a (MutArray a)
1965−writeAppendWith sizer = FL.foldlM' (snocWith sizer)
2055+writeAppendWith = appendWith
19662056
19672057-- | @append action@ mutates the array generated by @action@ to append the
19682058-- input stream. If there is no reserved space available in the array it is
@@ -1970,26 +2060,33 @@ writeAppendWith sizer = FL.foldlM' (snocWith sizer)
19702060--
19712061-- Note that the returned array may be a mutated version of original array.
19722062--
1973−-- >>> writeAppend = MutArray.writeAppendWith (* 2)
2063+-- >>> append = MutArray.appendWith (* 2)
19742064--
2065+{-# INLINE append #-}
2066+append :: forall m a. (MonadIO m, Unbox a) =>
2067+ m (MutArray a) -> Fold m a (MutArray a)
2068+append = appendWith (* 2)
2069+
2070+-- XXX Deprecate in major
2071+-- {-# DEPRECATED writeAppend "Please use append instead." #-}
19752072{-# INLINE writeAppend #-}
19762073writeAppend :: forall m a. (MonadIO m, Unbox a) =>
19772074 m (MutArray a) -> Fold m a (MutArray a)
1978−writeAppend = writeAppendWith (* 2)
2075+writeAppend = append
19792076
19802077-- XXX We can carry bound as well in the state to make sure we do not lose the
19812078-- remaining capacity. Need to check perf impact.
19822079--
1983−-- | Like 'writeNUnsafe' but takes a new array allocator @alloc size@ function
1984−-- as argument.
2080+-- | Like 'unsafeCreateOf' but takes a new array allocator @alloc size@
2081+-- function as argument.
19852082--
1986−-- >>> writeNWithUnsafe alloc n = MutArray.writeAppendNUnsafe (alloc n) n
2083+-- >>> unsafeCreateOfWith alloc n = MutArray.unsafeAppendN (alloc n) n
19872084--
19882085-- /Pre-release/
1989−{-# INLINE_NORMAL writeNWithUnsafe #-}
1990−writeNWithUnsafe :: forall m a. (MonadIO m, Unbox a)
2086+{-# INLINE_NORMAL unsafeCreateOfWith #-}
2087+unsafeCreateOfWith :: forall m a. (MonadIO m, Unbox a)
19912088 => (Int -> m (MutArray a)) -> Int -> Fold m a (MutArray a)
1992−writeNWithUnsafe alloc n = fromArrayUnsafe <$> FL.foldlM' step initial
2089+unsafeCreateOfWith alloc n = fromArrayUnsafe <$> FL.foldlM' step initial
19932090
19942091 where
19952092
@@ -2000,40 +2097,64 @@ writeNWithUnsafe alloc n = fromArrayUnsafe <$> FL.foldlM' step initial
20002097 return
20012098 $ ArrayUnsafe contents start (INDEX_NEXT(end,a))
20022099
2100+{-# DEPRECATED writeNWithUnsafe "Please use unsafeCreateOfWith instead." #-}
2101+{-# INLINE writeNWithUnsafe #-}
2102+writeNWithUnsafe :: forall m a. (MonadIO m, Unbox a)
2103+ => (Int -> m (MutArray a)) -> Int -> Fold m a (MutArray a)
2104+writeNWithUnsafe = unsafeCreateOfWith
2105+
20032106{-# INLINE_NORMAL writeNUnsafeAs #-}
20042107writeNUnsafeAs :: forall m a. (MonadIO m, Unbox a)
20052108 => PinnedState -> Int -> Fold m a (MutArray a)
2006−writeNUnsafeAs ps = writeNWithUnsafe (newAs ps)
2109+writeNUnsafeAs ps = unsafeCreateOfWith (newAs ps)
20072110
2008−-- | Like 'writeN' but does not check the array bounds when writing. The fold
2111+-- | Like 'createOf' but does not check the array bounds when writing. The fold
20092112-- driver must not call the step function more than 'n' times otherwise it will
20102113-- corrupt the memory and crash. This function exists mainly because any
20112114-- conditional in the step function blocks fusion causing 10x performance
20122115-- slowdown.
20132116--
2014−-- >>> writeNUnsafe = MutArray.writeNWithUnsafe MutArray.new
2117+-- >>> unsafeCreateOf = MutArray.unsafeCreateOfWith MutArray.emptyOf
20152118--
2016−{-# INLINE_NORMAL writeNUnsafe #-}
2119+{-# INLINE_NORMAL unsafeCreateOf #-}
2120+unsafeCreateOf :: forall m a. (MonadIO m, Unbox a)
2121+ => Int -> Fold m a (MutArray a)
2122+unsafeCreateOf = writeNUnsafeAs Unpinned
2123+
2124+{-# DEPRECATED writeNUnsafe "Please use unsafeCreateOf instead." #-}
2125+{-# INLINE writeNUnsafe #-}
20172126writeNUnsafe :: forall m a. (MonadIO m, Unbox a)
20182127 => Int -> Fold m a (MutArray a)
2019−writeNUnsafe = writeNUnsafeAs Unpinned
2128+writeNUnsafe = unsafeCreateOf
2129+
2130+-- | Like 'unsafeCreateOf' but creates a pinned array.
2131+{-# INLINE_NORMAL unsafePinnedCreateOf #-}
2132+unsafePinnedCreateOf :: forall m a. (MonadIO m, Unbox a)
2133+ => Int -> Fold m a (MutArray a)
2134+unsafePinnedCreateOf = writeNUnsafeAs Pinned
20202135
2021−-- | Like 'writeNUnsafe' but creates a pinned array.
2022−{-# INLINE_NORMAL pinnedWriteNUnsafe #-}
2136+{-# DEPRECATED pinnedWriteNUnsafe "Please use unsafePinnedCreateOf instead." #-}
2137+{-# INLINE pinnedWriteNUnsafe #-}
20232138pinnedWriteNUnsafe :: forall m a. (MonadIO m, Unbox a)
20242139 => Int -> Fold m a (MutArray a)
2025−pinnedWriteNUnsafe = writeNUnsafeAs Pinned
2140+pinnedWriteNUnsafe = unsafePinnedCreateOf
20262141
2027−-- | @writeNWith alloc n@ folds a maximum of @n@ elements into an array
2142+-- | @createOfWith alloc n@ folds a maximum of @n@ elements into an array
20282143-- allocated using the @alloc@ function.
20292144--
2030−-- >>> writeNWith alloc n = Fold.take n (MutArray.writeNWithUnsafe alloc n)
2031−-- >>> writeNWith alloc n = MutArray.writeAppendN (alloc n) n
2145+-- >>> createOfWith alloc n = Fold.take n (MutArray.unsafeCreateOfWith alloc n)
2146+-- >>> createOfWith alloc n = MutArray.appendN (alloc n) n
20322147--
2033−{-# INLINE_NORMAL writeNWith #-}
2148+{-# INLINE_NORMAL createOfWith #-}
2149+createOfWith :: forall m a. (MonadIO m, Unbox a)
2150+ => (Int -> m (MutArray a)) -> Int -> Fold m a (MutArray a)
2151+createOfWith alloc n = FL.take n (unsafeCreateOfWith alloc n)
2152+
2153+-- {-# DEPRECATED writeNWith "Please use createOfWith instead." #-}
2154+{-# INLINE writeNWith #-}
20342155writeNWith :: forall m a. (MonadIO m, Unbox a)
20352156 => (Int -> m (MutArray a)) -> Int -> Fold m a (MutArray a)
2036−writeNWith alloc n = FL.take n (writeNWithUnsafe alloc n)
2157+writeNWith = createOfWith
20372158
20382159{-# INLINE_NORMAL writeNAs #-}
20392160writeNAs ::
@@ -2041,28 +2162,42 @@ writeNAs ::
20412162 => PinnedState
20422163 -> Int
20432164 -> Fold m a (MutArray a)
2044−writeNAs ps = writeNWith (newAs ps)
2165+writeNAs ps = createOfWith (newAs ps)
20452166
2046−-- | @writeN n@ folds a maximum of @n@ elements from the input stream to an
2167+-- | @createOf n@ folds a maximum of @n@ elements from the input stream to an
20472168-- 'MutArray'.
20482169--
2049−-- >>> writeN = MutArray.writeNWith MutArray.new
2050−-- >>> writeN n = Fold.take n (MutArray.writeNUnsafe n)
2051−-- >>> writeN n = MutArray.writeAppendN n (MutArray.new n)
2170+-- >>> createOf = MutArray.createOfWith MutArray.new
2171+-- >>> createOf n = Fold.take n (MutArray.unsafeCreateOf n)
2172+-- >>> createOf n = MutArray.appendN n (MutArray.emptyOf n)
20522173--
2053−{-# INLINE_NORMAL writeN #-}
2174+{-# INLINE_NORMAL createOf #-}
2175+createOf :: forall m a. (MonadIO m, Unbox a) => Int -> Fold m a (MutArray a)
2176+createOf = writeNAs Unpinned
2177+
2178+-- XXX Deprecate in major
2179+-- {-# DEPRECATED writeN "Please use createOf instead." #-}
2180+{-# INLINE writeN #-}
20542181writeN :: forall m a. (MonadIO m, Unbox a) => Int -> Fold m a (MutArray a)
2055−writeN = writeNAs Unpinned
2182+writeN = createOf
2183+
2184+-- | Like 'createOf' but creates a pinned array.
2185+{-# INLINE_NORMAL pinnedCreateOf #-}
2186+pinnedCreateOf ::
2187+ forall m a. (MonadIO m, Unbox a)
2188+ => Int
2189+ -> Fold m a (MutArray a)
2190+pinnedCreateOf = writeNAs Pinned
20562191
2057−-- | Like 'writeN' but creates a pinned array.
2058−{-# INLINE_NORMAL pinnedWriteN #-}
2192+{-# DEPRECATED pinnedWriteN "Please use pinnedCreateOf instead." #-}
2193+{-# INLINE pinnedWriteN #-}
20592194pinnedWriteN ::
20602195 forall m a. (MonadIO m, Unbox a)
20612196 => Int
20622197 -> Fold m a (MutArray a)
2063−pinnedWriteN = writeNAs Pinned
2198+pinnedWriteN = pinnedCreateOf
20642199
2065−-- | Like writeNWithUnsafe but writes the array in reverse order.
2200+-- | Like unsafeCreateOfWith but writes the array in reverse order.
20662201--
20672202-- /Internal/
20682203{-# INLINE_NORMAL writeRevNWithUnsafe #-}
@@ -2083,7 +2218,7 @@ writeRevNWithUnsafe alloc n = fromArrayUnsafe <$> FL.foldlM' step initial
20832218 return
20842219 $ ArrayUnsafe contents ptr end
20852220
2086−-- | Like writeNWith but writes the array in reverse order.
2221+-- | Like createOfWith but writes the array in reverse order.
20872222--
20882223-- /Internal/
20892224{-# INLINE_NORMAL writeRevNWith #-}
@@ -2091,31 +2226,36 @@ writeRevNWith :: forall m a. (MonadIO m, Unbox a)
20912226 => (Int -> m (MutArray a)) -> Int -> Fold m a (MutArray a)
20922227writeRevNWith alloc n = FL.take n (writeRevNWithUnsafe alloc n)
20932228
2094−-- | Like writeN but writes the array in reverse order.
2229+-- | Like 'createOf' but writes the array in reverse order.
20952230--
20962231-- /Pre-release/
2097−{-# INLINE_NORMAL writeRevN #-}
2232+{-# INLINE_NORMAL revCreateOf #-}
2233+revCreateOf :: forall m a. (MonadIO m, Unbox a) => Int -> Fold m a (MutArray a)
2234+revCreateOf = writeRevNWith new
2235+
2236+{-# DEPRECATED writeRevN "Please use revCreateOf instead." #-}
2237+{-# INLINE writeRevN #-}
20982238writeRevN :: forall m a. (MonadIO m, Unbox a) => Int -> Fold m a (MutArray a)
2099−writeRevN = writeRevNWith new
2239+writeRevN = revCreateOf
21002240
21012241-- | @pinnedWriteNAligned align n@ folds a maximum of @n@ elements from the
21022242-- input stream to a 'MutArray' aligned to the given size.
21032243--
2104−-- >>> pinnedWriteNAligned align = MutArray.writeNWith (MutArray.pinnedNewAligned align)
2105−-- >>> pinnedWriteNAligned align n = MutArray.writeAppendN n (MutArray.pinnedNewAligned align n)
2244+-- >>> pinnedWriteNAligned align = MutArray.createOfWith (MutArray.pinnedNewAligned align)
2245+-- >>> pinnedWriteNAligned align n = MutArray.appendN n (MutArray.pinnedNewAligned align n)
21062246--
21072247-- /Pre-release/
21082248--
21092249{-# INLINE_NORMAL pinnedWriteNAligned #-}
21102250pinnedWriteNAligned :: forall m a. (MonadIO m, Unbox a)
21112251 => Int -> Int -> Fold m a (MutArray a)
2112−pinnedWriteNAligned align = writeNWith (pinnedNewAligned align)
2252+pinnedWriteNAligned align = createOfWith (pinnedNewAligned align)
21132253
21142254-- XXX Buffer to a list instead?
21152255
21162256-- | Buffer a stream into a stream of arrays.
21172257--
2118−-- >>> buildChunks n = Fold.many (MutArray.writeN n) Fold.toStreamK
2258+-- >>> buildChunks n = Fold.many (MutArray.createOf n) Fold.toStreamK
21192259--
21202260-- Breaking an array into an array stream can be useful to consume a large
21212261-- array sequentially such that memory of the array is released incrementatlly.
@@ -2127,9 +2267,10 @@ pinnedWriteNAligned align = writeNWith (pinnedNewAligned align)
21272267{-# INLINE_NORMAL buildChunks #-}
21282268buildChunks :: (MonadIO m, Unbox a) =>
21292269 Int -> Fold m a (StreamK n (MutArray a))
2130−buildChunks n = FL.many (writeN n) FL.toStreamK
2270+buildChunks n = FL.many (createOf n) FL.toStreamK
21312271
21322272{-# DEPRECATED writeChunks "Please use buildChunks instead." #-}
2273+{-# INLINE writeChunks #-}
21332274writeChunks :: (MonadIO m, Unbox a) =>
21342275 Int -> Fold m a (StreamK n (MutArray a))
21352276writeChunks = buildChunks
@@ -2137,29 +2278,29 @@ writeChunks = buildChunks
21372278{-# INLINE_NORMAL writeWithAs #-}
21382279writeWithAs :: forall m a. (MonadIO m, Unbox a)
21392280 => PinnedState -> Int -> Fold m a (MutArray a)
2140−-- writeWithAs ps n = FL.rmapM rightSize $ writeAppendWith (* 2) (newAs ps n)
2281+-- writeWithAs ps n = FL.rmapM rightSize $ appendWith (* 2) (newAs ps n)
21412282writeWithAs ps elemCount =
21422283 FL.rmapM extract $ FL.foldlM' step initial
21432284
21442285 where
21452286
21462287 initial = do
2147− when (elemCount < 0) $ error "writeWith: elemCount is negative"
2288+ when (elemCount < 0) $ error "createWith: elemCount is negative"
21482289 newAs ps elemCount
21492290
21502291 step arr@(MutArray _ start end bound) x
21512292 | INDEX_NEXT(end,a) > bound = do
21522293 let oldSize = end - start
21532294 newSize = max (oldSize * 2) 1
2154− arr1 <- liftIO $ reallocExplicit (SIZE_OF(a)) newSize arr
2295+ arr1 <- liftIO $ reallocExplicitAs ps (SIZE_OF(a)) newSize arr
21552296 snocUnsafe arr1 x
21562297 step arr x = snocUnsafe arr x
21572298
21582299 extract = liftIO . rightSize
21592300
2160−-- XXX Compare writeWith with fromStreamD which uses an array of streams
2301+-- XXX Compare createWith with fromStreamD which uses an array of streams
21612302-- implementation. We can write this using buildChunks above if that is faster.
2162−-- If writeWith is faster then we should use that to implement
2303+-- If createWith is faster then we should use that to implement
21632304-- fromStreamD.
21642305--
21652306-- XXX The realloc based implementation needs to make one extra copy if we use
@@ -2174,39 +2315,56 @@ writeWithAs ps elemCount =
21742315-- XXX check if GHC's memory allocator is efficient enough. We can try the C
21752316-- malloc to compare against.
21762317
2177−-- | @writeWith minCount@ folds the whole input to a single array. The array
2318+-- | @createWith minCount@ folds the whole input to a single array. The array
21782319-- starts at a size big enough to hold minCount elements, the size is doubled
21792320-- every time the array needs to be grown.
21802321--
21812322-- /Caution! Do not use this on infinite streams./
21822323--
2183−-- >>> f n = MutArray.writeAppendWith (* 2) (MutArray.new n)
2184−-- >>> writeWith n = Fold.rmapM MutArray.rightSize (f n)
2185−-- >>> writeWith n = Fold.rmapM MutArray.fromChunksK (MutArray.buildChunks n)
2324+-- >>> f n = MutArray.appendWith (* 2) (MutArray.emptyOf n)
2325+-- >>> createWith n = Fold.rmapM MutArray.rightSize (f n)
2326+-- >>> createWith n = Fold.rmapM MutArray.fromChunksK (MutArray.buildChunks n)
21862327--
21872328-- /Pre-release/
2188−{-# INLINE_NORMAL writeWith #-}
2329+{-# INLINE_NORMAL createWith #-}
2330+createWith :: forall m a. (MonadIO m, Unbox a)
2331+ => Int -> Fold m a (MutArray a)
2332+-- createWith n = FL.rmapM rightSize $ appendWith (* 2) (emptyOf n)
2333+createWith = writeWithAs Unpinned
2334+
2335+{-# DEPRECATED writeWith "Please use createWith instead." #-}
2336+{-# INLINE writeWith #-}
21892337writeWith :: forall m a. (MonadIO m, Unbox a)
21902338 => Int -> Fold m a (MutArray a)
2191−-- writeWith n = FL.rmapM rightSize $ writeAppendWith (* 2) (new n)
2192−writeWith = writeWithAs Unpinned
2339+writeWith = createWith
21932340
21942341-- | Fold the whole input to a single array.
21952342--
2196−-- Same as 'writeWith' using an initial array size of 'arrayChunkBytes' bytes
2343+-- Same as 'createWith' using an initial array size of 'arrayChunkBytes' bytes
21972344-- rounded up to the element size.
21982345--
21992346-- /Caution! Do not use this on infinite streams./
22002347--
2348+{-# INLINE create #-}
2349+create :: forall m a. (MonadIO m, Unbox a) => Fold m a (MutArray a)
2350+create = createWith (allocBytesToElemCount (undefined :: a) arrayChunkBytes)
2351+
2352+-- XXX Deprecate in major
2353+-- {-# DEPRECATED write "Please use create instead." #-}
22012354{-# INLINE write #-}
22022355write :: forall m a. (MonadIO m, Unbox a) => Fold m a (MutArray a)
2203−write = writeWith (allocBytesToElemCount (undefined :: a) arrayChunkBytes)
2356+write = create
22042357
2205−-- | Like 'write' but creates a pinned array.
2358+-- | Like 'create' but creates a pinned array.
2359+{-# INLINE pinnedCreate #-}
2360+pinnedCreate :: forall m a. (MonadIO m, Unbox a) => Fold m a (MutArray a)
2361+pinnedCreate =
2362+ writeWithAs Pinned (allocBytesToElemCount (undefined :: a) arrayChunkBytes)
2363+
2364+{-# DEPRECATED pinnedWrite "Please use pinnedCreate instead." #-}
22062365{-# INLINE pinnedWrite #-}
22072366pinnedWrite :: forall m a. (MonadIO m, Unbox a) => Fold m a (MutArray a)
2208−pinnedWrite =
2209− writeWithAs Pinned (allocBytesToElemCount (undefined :: a) arrayChunkBytes)
2367+pinnedWrite = pinnedCreate
22102368
22112369-------------------------------------------------------------------------------
22122370-- construct from streams, known size
@@ -2226,17 +2384,18 @@ fromStreamDNAs ps limit str = do
22262384 liftIO $ pokeAt ptr arrContents x
22272385 return $ INDEX_NEXT(ptr,a)
22282386
2229−-- | Use the 'writeN' fold instead.
2387+-- | Use the 'createOf' fold instead.
22302388--
2231−-- >>> fromStreamN n = Stream.fold (MutArray.writeN n)
2389+-- >>> fromStreamN n = Stream.fold (MutArray.createOf n)
22322390--
22332391{-# INLINE_NORMAL fromStreamN #-}
22342392fromStreamN :: forall m a. (MonadIO m, Unbox a)
22352393 => Int -> D.Stream m a -> m (MutArray a)
2236−-- fromStreamDN n = D.fold (writeN n)
2394+-- fromStreamDN n = D.fold (createOf n)
22372395fromStreamN = fromStreamDNAs Unpinned
22382396
22392397{-# DEPRECATED fromStreamDN "Please use fromStreamN instead." #-}
2398+{-# INLINE fromStreamDN #-}
22402399fromStreamDN :: forall m a. (MonadIO m, Unbox a)
22412400 => Int -> D.Stream m a -> m (MutArray a)
22422401fromStreamDN = fromStreamN
@@ -2259,20 +2418,20 @@ pinnedFromListN n xs = fromStreamDNAs Pinned n $ D.fromList xs
22592418-- /Pre-release/
22602419{-# INLINE fromListRevN #-}
22612420fromListRevN :: (MonadIO m, Unbox a) => Int -> [a] -> m (MutArray a)
2262−fromListRevN n xs = D.fold (writeRevN n) $ D.fromList xs
2421+fromListRevN n xs = D.fold (revCreateOf n) $ D.fromList xs
22632422
22642423-- | Convert a pure stream in Identity monad to a mutable array.
22652424{-# INLINABLE fromPureStreamN #-}
22662425fromPureStreamN :: (MonadIO m, Unbox a) =>
22672426 Int -> Stream Identity a -> m (MutArray a)
22682427fromPureStreamN n xs =
2269− D.fold (writeN n) $ D.morphInner (return . runIdentity) xs
2428+ D.fold (createOf n) $ D.morphInner (return . runIdentity) xs
22702429
22712430-- | Convert a pure stream in Identity monad to a mutable array.
22722431{-# INLINABLE fromPureStream #-}
22732432fromPureStream :: (MonadIO m, Unbox a) => Stream Identity a -> m (MutArray a)
22742433fromPureStream xs =
2275− D.fold write $ D.morphInner (return . runIdentity) xs
2434+ D.fold create $ D.morphInner (return . runIdentity) xs
22762435
22772436{-# INLINABLE fromPtrN #-}
22782437fromPtrN :: MonadIO m => Int -> Ptr Word8 -> m (MutArray Word8)
@@ -2281,7 +2440,7 @@ fromPtrN len addr = do
22812440 -- XXX We can implement a stream copy in a similar way by streaming Word64
22822441 -- first and then remaining Word8.
22832442 arr <- new len
2284− _ <- asUnpinnedPtrUnsafe arr
2443+ _ <- unsafeAsPtr arr
22852444 (\ptr -> liftIO $ c_memcpy ptr addr (fromIntegral len))
22862445 return (arr {arrEnd = len})
22872446
@@ -2297,7 +2456,7 @@ fromByteStr# addr = do
22972456 len <- liftIO $ c_strlen (Ptr addr)
22982457 let lenInt = fromIntegral len
22992458 arr <- new lenInt
2300− _ <- asUnpinnedPtrUnsafe arr (\ptr -> liftIO $ c_memcpy ptr (Ptr addr) len)
2459+ _ <- unsafeAsPtr arr (\ptr -> liftIO $ c_memcpy ptr (Ptr addr) len)
23012460 return (arr {arrEnd = lenInt})
23022461
23032462-------------------------------------------------------------------------------
@@ -2356,6 +2515,7 @@ fromChunksK :: (Unbox a, MonadIO m) =>
23562515fromChunksK = fromChunkskAs Unpinned
23572516
23582517{-# DEPRECATED fromArrayStreamK "Please use fromChunksK instead." #-}
2518+{-# INLINE fromArrayStreamK #-}
23592519fromArrayStreamK :: (Unbox a, MonadIO m) =>
23602520 StreamK m (MutArray a) -> m (MutArray a)
23612521fromArrayStreamK = fromChunksK
@@ -2367,7 +2527,7 @@ fromStreamDAs ps m =
23672527 arrayStreamKFromStreamDAs Unpinned m >>= fromChunkskAs ps
23682528
23692529-- | Create an 'Array' from a stream. This is useful when we want to create a
2370−-- single array from a stream of unknown size. 'writeN' is at least twice
2530+-- single array from a stream of unknown size. 'createOf' is at least twice
23712531-- as efficient when the size is already known.
23722532--
23732533-- Note that if the input stream is too large memory allocation for the array
@@ -2379,19 +2539,19 @@ fromStreamDAs ps m =
23792539fromStream :: (MonadIO m, Unbox a) => Stream m a -> m (MutArray a)
23802540fromStream = fromStreamDAs Unpinned
23812541
2382−-- fromStream (Stream m) = P.fold write m
2542+-- fromStream (Stream m) = P.fold create m
23832543-- CAUTION: a very large number (millions) of arrays can degrade performance
23842544-- due to GC overhead because we need to buffer the arrays before we flatten
23852545-- all the arrays.
23862546--
2387−-- XXX Compare if this is faster or "fold write".
2547+-- XXX Compare if this is faster or "fold create".
23882548--
23892549-- | We could take the approach of doubling the memory allocation on each
23902550-- overflow. This would result in more or less the same amount of copying as in
23912551-- the chunking approach. However, if we have to shrink in the end then it may
23922552-- result in an extra copy of the entire data.
23932553--
2394−-- >>> fromStreamD = StreamD.fold MutArray.write
2554+-- >>> fromStreamD = StreamD.fold MutArray.create
23952555--
23962556{-# INLINE fromStreamD #-}
23972557{-# DEPRECATED fromStreamD "Please use fromStream instead." #-}
@@ -2421,6 +2581,10 @@ fromListRev xs = fromListRevN (Prelude.length xs) xs
24212581-- Cloning
24222582-------------------------------------------------------------------------------
24232583
2584+-- Arrays are aligned on 64-bit boundaries. The fastest way to copy an array is
2585+-- to unsafeCast it to Word64, read it, write it to Word64 array and unsafeCast
2586+-- it again. We can use SIMD read/write as well.
2587+
24242588{-# INLINE cloneAs #-}
24252589cloneAs ::
24262590 ( MonadIO m
@@ -2512,7 +2676,7 @@ spliceWith :: forall m a. (MonadIO m, Unbox a) =>
25122676 (Int -> Int -> Int) -> MutArray a -> MutArray a -> m (MutArray a)
25132677spliceWith sizer dst@(MutArray _ start end bound) src = do
25142678{-
2515− let f = writeAppendWith (`sizer` byteLength src) (return dst)
2679+ let f = appendWith (`sizer` byteLength src) (return dst)
25162680 in D.fold f (toStreamD src)
25172681-}
25182682 assert (end <= bound) (return ())
@@ -2580,7 +2744,7 @@ splitOn predicate arr =
25802744{-# INLINE breakOn #-}
25812745breakOn :: MonadIO m
25822746 => Word8 -> MutArray Word8 -> m (MutArray Word8, Maybe (MutArray Word8))
2583−breakOn sep arr@MutArray{..} = asUnpinnedPtrUnsafe arr $ \p -> liftIO $ do
2747+breakOn sep arr@MutArray{..} = unsafeAsPtr arr $ \p -> liftIO $ do
25842748 -- XXX We do not need memchr here, we can use a Haskell equivalent.
25852749 -- Need efficient stream based primitives that work on Word64.
25862750 loc <- c_memchr p sep (fromIntegral $ byteLength arr)
@@ -2603,33 +2767,41 @@ breakOn sep arr@MutArray{..} = asUnpinnedPtrUnsafe arr $ \p -> liftIO $ do
26032767 }
26042768 )
26052769
2770+-- | Like 'splitAt' but does not check whether the index is valid.
2771+--
2772+{-# INLINE unsafeSplitAt #-}
2773+unsafeSplitAt :: forall a. Unbox a =>
2774+ Int -> MutArray a -> (MutArray a, MutArray a)
2775+unsafeSplitAt i MutArray{..} =
2776+ let off = i * SIZE_OF(a)
2777+ p = arrStart + off
2778+ in ( MutArray
2779+ { arrContents = arrContents
2780+ , arrStart = arrStart
2781+ , arrEnd = p
2782+ , arrBound = p
2783+ }
2784+ , MutArray
2785+ { arrContents = arrContents
2786+ , arrStart = p
2787+ , arrEnd = arrEnd
2788+ , arrBound = arrBound
2789+ }
2790+ )
2791+
26062792-- | Create two slices of an array without copying the original array. The
26072793-- specified index @i@ is the first index of the second slice.
26082794--
26092795{-# INLINE splitAt #-}
26102796splitAt :: forall a. Unbox a => Int -> MutArray a -> (MutArray a, MutArray a)
2611−splitAt i arr@MutArray{..} =
2797+splitAt i arr =
26122798 let maxIndex = length arr - 1
26132799 in if i < 0
26142800 then error "sliceAt: negative array index"
26152801 else if i > maxIndex
26162802 then error $ "sliceAt: specified array index " ++ show i
26172803 ++ " is beyond the maximum index " ++ show maxIndex
2618− else let off = i * SIZE_OF(a)
2619− p = arrStart + off
2620− in ( MutArray
2621− { arrContents = arrContents
2622− , arrStart = arrStart
2623− , arrEnd = p
2624− , arrBound = p
2625− }
2626− , MutArray
2627− { arrContents = arrContents
2628− , arrStart = p
2629− , arrEnd = arrEnd
2630− , arrBound = arrBound
2631− }
2632− )
2804+ else unsafeSplitAt i arr
26332805
26342806-------------------------------------------------------------------------------
26352807-- Casting
@@ -2679,9 +2851,13 @@ cast arr =
26792851-- guarantees that unsafe calls will be performed in the calling thread. Making
26802852-- it safe to pass heap-allocated objects to unsafe functions.
26812853
2682−-- Should we just name it asPtr, the unsafety is implicit for any pointer
2854+-- XXX Should we just name it asPtr, the unsafety is implicit for any pointer
26832855-- operations. And we are safe from Haskell perspective because we will be
26842856-- pinning the memory.
2857+--
2858+-- XXX we cannot pass the length of the ptr here as in some cases it may not be
2859+-- available e.g. a null terminated C string. However, we can create another
2860+-- flavor of the API e.g. asPtrN.
26852861
26862862-- | Use a @MutArray a@ as @Ptr a@. This is useful when we want to pass an
26872863-- array as a pointer to some operating system call or to a "safe" FFI call.
@@ -2699,16 +2875,21 @@ cast arr =
26992875--
27002876-- /Pre-release/
27012877--
2878+{-# INLINE unsafePinnedAsPtr #-}
2879+unsafePinnedAsPtr :: MonadIO m => MutArray a -> (Ptr a -> m b) -> m b
2880+unsafePinnedAsPtr arr f =
2881+ Unboxed.unsafePinnedAsPtr
2882+ (arrContents arr) (\ptr -> f (ptr `plusPtr` arrStart arr))
2883+
2884+{-# DEPRECATED asPtrUnsafe "Please use unsafePinnedAsPtr instead." #-}
27022885{-# INLINE asPtrUnsafe #-}
27032886asPtrUnsafe :: MonadIO m => MutArray a -> (Ptr a -> m b) -> m b
2704−asPtrUnsafe arr f =
2705− Unboxed.asPtrUnsafe
2706− (arrContents arr) (\ptr -> f (ptr `plusPtr` arrStart arr))
2887+asPtrUnsafe = unsafePinnedAsPtr
27072888
2708−{-# INLINE asUnpinnedPtrUnsafe #-}
2709−asUnpinnedPtrUnsafe :: MonadIO m => MutArray a -> (Ptr a -> m b) -> m b
2710−asUnpinnedPtrUnsafe arr f =
2711− Unboxed.asUnpinnedPtrUnsafe
2889+{-# INLINE unsafeAsPtr #-}
2890+unsafeAsPtr :: MonadIO m => MutArray a -> (Ptr a -> m b) -> m b
2891+unsafeAsPtr arr f =
2892+ Unboxed.unsafeAsPtr
27122893 (arrContents arr) (\ptr -> f (ptr `plusPtr` arrStart arr))
27132894
27142895-------------------------------------------------------------------------------
@@ -2770,19 +2951,11 @@ byteEq arr1 arr2 = fmap (EQ ==) $ byteCmp arr1 arr2
27702951-- can leave some memory unused. They can split the last array to fit it
27712952-- exactly in the space.
27722953
2773−-- | Parser @pCompactLE maxElems@ coalesces adjacent arrays in the input stream
2774−-- only if the combined size would be less than or equal to @maxElems@
2775−-- elements. Note that it won't split an array if the original array is already
2776−-- larger than maxElems.
2777−--
2778−-- @maxElems@ must be greater than 0.
2779−--
2780−-- /Internal/
2781−{-# INLINE_NORMAL pCompactLE #-}
2782−pCompactLE ::
2954+{-# INLINE_NORMAL pCompactLeAs #-}
2955+pCompactLeAs ::
27832956 forall m a. (MonadIO m, Unbox a)
2784− => Int -> Parser (MutArray a) m (MutArray a)
2785−pCompactLE maxElems = Parser step initial extract
2957+ => PinnedState -> Int -> Parser (MutArray a) m (MutArray a)
2958+pCompactLeAs ps maxElems = Parser step initial extract
27862959
27872960 where
27882961
@@ -2813,7 +2986,8 @@ pCompactLE maxElems = Parser step initial extract
28132986 else do
28142987 buf1 <-
28152988 if byteCapacity buf < maxBytes
2816− then realloc maxBytes buf
2989+ then liftIO $ reallocExplicitAs
2990+ ps (SIZE_OF(a)) maxBytes buf
28172991 else return buf
28182992 buf2 <- spliceUnsafe buf1 arr
28192993 return $ Parser.Partial 0 (Just buf2)
@@ -2821,6 +2995,30 @@ pCompactLE maxElems = Parser step initial extract
28212995 extract Nothing = return $ Parser.Done 0 nil
28222996 extract (Just buf) = return $ Parser.Done 0 buf
28232997
2998+-- | Parser @pCompactLE maxElems@ coalesces adjacent arrays in the input stream
2999+-- only if the combined size would be less than or equal to @maxElems@
3000+-- elements. Note that it won't split an array if the original array is already
3001+-- larger than maxElems.
3002+--
3003+-- @maxElems@ must be greater than 0.
3004+--
3005+-- Generates unpinned arrays irrespective of the pinning status of input
3006+-- arrays.
3007+--
3008+-- /Internal/
3009+{-# INLINE pCompactLE #-}
3010+pCompactLE ::
3011+ forall m a. (MonadIO m, Unbox a)
3012+ => Int -> Parser (MutArray a) m (MutArray a)
3013+pCompactLE = pCompactLeAs Unpinned
3014+
3015+-- | Pinned version of 'pCompactLE'.
3016+{-# INLINE pPinnedCompactLE #-}
3017+pPinnedCompactLE ::
3018+ forall m a. (MonadIO m, Unbox a)
3019+ => Int -> Parser (MutArray a) m (MutArray a)
3020+pPinnedCompactLE = pCompactLeAs Pinned
3021+
28243022data SpliceState s arr
28253023 = SpliceInitial s
28263024 | SpliceBuffering s arr
@@ -2832,18 +3030,10 @@ data SpliceState s arr
28323030-- immutable array never has additional space so a new array is allocated
28333031-- instead of mutating it.
28343032
2835−-- | Scan @rCompactLE maxElems@ coalesces adjacent arrays in the input stream
2836−-- only if the combined size would be less than or equal to @maxElems@
2837−-- elements. Note that it won't split an array if the original array is already
2838−-- larger than maxElems.
2839−--
2840−-- @maxElems@ must be greater than 0.
2841−--
2842−-- /Internal/
2843−{-# INLINE_NORMAL rCompactLE #-}
2844−rCompactLE :: forall m a. (MonadIO m, Unbox a)
2845− => Int -> D.Stream m (MutArray a) -> D.Stream m (MutArray a)
2846−rCompactLE maxElems (D.Stream step state) =
3033+{-# INLINE_NORMAL compactLeAs #-}
3034+compactLeAs :: forall m a. (MonadIO m, Unbox a)
3035+ => PinnedState -> Int -> D.Stream m (MutArray a) -> D.Stream m (MutArray a)
3036+compactLeAs ps maxElems (D.Stream step state) =
28473037 D.Stream step' (SpliceInitial state)
28483038
28493039 where
@@ -2879,7 +3069,8 @@ rCompactLE maxElems (D.Stream step state) =
28793069 D.Skip (SpliceYielding buf (SpliceBuffering s arr))
28803070 else do
28813071 buf1 <- if byteCapacity buf < maxBytes
2882− then realloc maxBytes buf
3072+ then liftIO $ reallocExplicitAs
3073+ ps (SIZE_OF(a)) maxBytes buf
28833074 else return buf
28843075 buf2 <- spliceUnsafe buf1 arr
28853076 return $ D.Skip (SpliceBuffering s buf2)
@@ -2890,14 +3081,12 @@ rCompactLE maxElems (D.Stream step state) =
28903081
28913082 step' _ (SpliceYielding arr next) = return $ D.Yield arr next
28923083
2893−-- | Fold @fCompactGE minElems@ coalesces adjacent arrays in the input stream
2894−-- until the size becomes greater than or equal to @minElems@.
2895−--
2896−{-# INLINE_NORMAL fCompactGE #-}
2897−fCompactGE ::
3084+
3085+{-# INLINE_NORMAL fCompactGeAs #-}
3086+fCompactGeAs ::
28983087 forall m a. (MonadIO m, Unbox a)
2899− => Int -> FL.Fold m (MutArray a) (MutArray a)
2900−fCompactGE minElems = Fold step initial extract extract
3088+ => PinnedState -> Int -> FL.Fold m (MutArray a) (MutArray a)
3089+fCompactGeAs ps minElems = Fold step initial extract extract
29013090
29023091 where
29033092
@@ -2925,7 +3114,8 @@ fCompactGE minElems = Fold step initial extract extract
29253114 let len = byteLength buf + byteLength arr
29263115 buf1 <-
29273116 if byteCapacity buf < len
2928− then realloc (max len minBytes) buf
3117+ then liftIO $ reallocExplicitAs
3118+ ps (SIZE_OF(a)) (max minBytes len) buf
29293119 else return buf
29303120 buf2 <- spliceUnsafe buf1 arr
29313121 if len >= minBytes
@@ -2935,15 +3125,30 @@ fCompactGE minElems = Fold step initial extract extract
29353125 extract Nothing = return nil
29363126 extract (Just buf) = return buf
29373127
2938−-- | Like 'compactGE' but for transforming folds instead of stream.
2939−--
2940−-- >>> lCompactGE n = Fold.many (MutArray.fCompactGE n)
3128+-- | Fold @fCompactGE minElems@ coalesces adjacent arrays in the input stream
3129+-- until the size becomes greater than or equal to @minElems@.
29413130--
2942−{-# INLINE_NORMAL lCompactGE #-}
2943−lCompactGE :: forall m a. (MonadIO m, Unbox a)
2944− => Int -> Fold m (MutArray a) () -> Fold m (MutArray a) ()
2945−-- lCompactGE n = Fold.many (fCompactGE n)
2946−lCompactGE minElems (Fold step1 initial1 _ final1) =
3131+-- Generates unpinned arrays irrespective of the pinning status of input
3132+-- arrays.
3133+{-# INLINE fCompactGE #-}
3134+fCompactGE ::
3135+ forall m a. (MonadIO m, Unbox a)
3136+ => Int -> FL.Fold m (MutArray a) (MutArray a)
3137+fCompactGE = fCompactGeAs Unpinned
3138+
3139+-- | Pinned version of 'fCompactGE'.
3140+{-# INLINE fPinnedCompactGE #-}
3141+fPinnedCompactGE ::
3142+ forall m a. (MonadIO m, Unbox a)
3143+ => Int -> FL.Fold m (MutArray a) (MutArray a)
3144+fPinnedCompactGE = fCompactGeAs Pinned
3145+
3146+{-# INLINE_NORMAL lCompactGeAs #-}
3147+lCompactGeAs :: forall m a. (MonadIO m, Unbox a)
3148+ => PinnedState -> Int -> Fold m (MutArray a) () -> Fold m (MutArray a) ()
3149+-- The fold version turns out to be a little bit slower.
3150+-- lCompactGeAs ps n = FL.many (fCompactGeAs ps n)
3151+lCompactGeAs ps minElems (Fold step1 initial1 _ final1) =
29473152 Fold step initial extract final
29483153
29493154 where
@@ -2981,7 +3186,8 @@ lCompactGE minElems (Fold step1 initial1 _ final1) =
29813186 step (Tuple' (Just buf) r1) arr = do
29823187 let len = byteLength buf + byteLength arr
29833188 buf1 <- if byteCapacity buf < len
2984− then realloc (max minBytes len) buf
3189+ then liftIO $ reallocExplicitAs
3190+ ps (SIZE_OF(a)) (max minBytes len) buf
29853191 else return buf
29863192 buf2 <- spliceUnsafe buf1 arr
29873193 runInner len r1 buf2
@@ -3001,6 +3207,23 @@ lCompactGE minElems (Fold step1 initial1 _ final1) =
30013207 FL.Partial rr -> final1 rr
30023208 FL.Done _ -> return ()
30033209
3210+-- | Like 'compactGE' but for transforming folds instead of stream.
3211+--
3212+-- >>> lCompactGE n = Fold.many (MutArray.fCompactGE n)
3213+--
3214+-- Generates unpinned arrays irrespective of the pinning status of input
3215+-- arrays.
3216+{-# INLINE lCompactGE #-}
3217+lCompactGE :: forall m a. (MonadIO m, Unbox a)
3218+ => Int -> Fold m (MutArray a) () -> Fold m (MutArray a) ()
3219+lCompactGE = lCompactGeAs Unpinned
3220+
3221+-- | Pinned version of 'lCompactGE'.
3222+{-# INLINE lPinnedCompactGE #-}
3223+lPinnedCompactGE :: forall m a. (MonadIO m, Unbox a)
3224+ => Int -> Fold m (MutArray a) () -> Fold m (MutArray a) ()
3225+lPinnedCompactGE = lCompactGeAs Pinned
3226+
30043227-- | @compactGE n stream@ coalesces adjacent arrays in the @stream@ until
30053228-- the size becomes greater than or equal to @n@.
30063229--