@@ -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+ , asPtrUnsafe -- XXX rename to unsafePinnedAsPtr?
46+ , asUnpinnedPtrUnsafe -- XXX rename to 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
@@ -103,7 +101,7 @@ module Streamly.Internal.Data.MutArray.Type
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
@@ -275,6 +273,25 @@ module Streamly.Internal.Data.MutArray.Type
275273 , getIndicesWith
276274 , resize
277275 , resizeExp
276+ , nil
277+ , new
278+ , pinnedNew
279+ , pinnedNewBytes
280+ , writeAppendNUnsafe
281+ , writeAppendN
282+ , writeAppendWith
283+ , writeAppend
284+ , writeNWithUnsafe
285+ , writeNWith
286+ , writeNUnsafe
287+ , pinnedWriteNUnsafe
288+ , writeN
289+ , pinnedWriteN
290+ , pinnedWriteNAligned -- XXX not required
291+ , writeWith
292+ , write
293+ , pinnedWrite
294+ , writeRevN
278295 )
279296where
280297
@@ -456,6 +473,8 @@ isPinned MutArray{..} = Unboxed.isPinned arrContents
456473-- we need more than that. See stg_pinnedNewAlignedByteArrayzh and
457474-- allocatePinned in GHC source.
458475
476+-- XXX Rename to emptyAlignedWith, alignSize should be first arg.
477+
459478-- | @newArrayWith allocator alignment count@ allocates a new array of zero
460479-- length and with a capacity to hold @count@ elements, using @allocator
461480-- size alignment@ as the memory allocator function.
@@ -479,12 +498,25 @@ newArrayWith alloc alignSize count = do
479498 , arrBound = size
480499 }
481500
501+-- For arrays "nil" sounds a bit odd. empty is better. The only problem with
502+-- empty is that it is also used by the Alternative type class. But assuming we
503+-- will mostly import the Array module qualified this should be fine.
504+
505+-- | Create an empty array.
506+empty ::
507+#ifdef DEVBUILD
508+ Unbox a =>
509+#endif
510+ MutArray a
511+empty = MutArray Unboxed.empty 0 0 0
512+
513+{-# DEPRECATED nil "Please use empty instead." #-}
482514nil ::
483515#ifdef DEVBUILD
484516 Unbox a =>
485517#endif
486518 MutArray a
487−nil = MutArray Unboxed.nil 0 0 0
519+nil = empty
488520
489521{-# INLINE newBytesAs #-}
490522newBytesAs :: MonadIO m =>
@@ -507,6 +539,7 @@ newBytesAs ps bytes = do
507539--
508540-- /Pre-release/
509541{-# INLINE pinnedNewBytes #-}
542+{-# DEPRECATED pinnedNewBytes "Please use pinnedEmptyOf with appropriate calculation" #-}
510543pinnedNewBytes :: MonadIO m =>
511544#ifdef DEVBUILD
512545 Unbox a =>
@@ -531,21 +564,31 @@ newAs ps =
531564 (error "new: alignment is not used in unpinned arrays.")
532565
533566-- 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−--
567+
568+-- | Allocates a pinned array of zero length but growable to the specified
569+-- capacity without reallocation.
570+{-# INLINE pinnedEmptyOf #-}
571+pinnedEmptyOf :: forall m a. (MonadIO m, Unbox a) => Int -> m (MutArray a)
572+pinnedEmptyOf = newAs Pinned
573+
574+-- XXX Deprecate in major
575+-- {-# DEPRECATED pinnedNew "Please use pinnedEmptyOf instead." #-}
539576{-# INLINE pinnedNew #-}
540577pinnedNew :: forall m a. (MonadIO m, Unbox a) => Int -> m (MutArray a)
541−pinnedNew = newAs Pinned
578+pinnedNew = pinnedEmptyOf
542579
543−-- | Allocates an empty unpinned array that can hold 'count' items. The memory
544−-- of the array is uninitialized.
580+-- | Allocates an unpinned array of zero length but growable to the specified
581+-- capacity without reallocation.
545582--
583+{-# INLINE emptyOf #-}
584+emptyOf :: (MonadIO m, Unbox a) => Int -> m (MutArray a)
585+emptyOf = newAs Unpinned
586+
587+-- XXX Deprecate in major
588+-- {-# DEPRECATED new "Please use emptyOf instead." #-}
546589{-# INLINE new #-}
547590new :: (MonadIO m, Unbox a) => Int -> m (MutArray a)
548−new = newAs Unpinned
591+new = emptyOf
549592
550593-------------------------------------------------------------------------------
551594-- Random writes
@@ -890,6 +933,7 @@ grow nElems arr@MutArray{..} = do
890933 else realloc req arr
891934
892935{-# DEPRECATED resize "Please use grow instead." #-}
936+{-# INLINE resize #-}
893937resize :: forall m a. (MonadIO m, Unbox a) =>
894938 Int -> MutArray a -> m (MutArray a)
895939resize = grow
@@ -913,6 +957,7 @@ growExp nElems arr@MutArray{..} = do
913957 else realloc req1 arr
914958
915959{-# DEPRECATED resizeExp "Please use growExp instead." #-}
960+{-# INLINE resizeExp #-}
916961resizeExp :: forall m a. (MonadIO m, Unbox a) =>
917962 Int -> MutArray a -> m (MutArray a)
918963resizeExp = growExp
@@ -1246,6 +1291,7 @@ indexReaderWith liftio (D.Stream stepi sti) = Unfold step inject
12461291 D.Stop -> return D.Stop
12471292
12481293{-# DEPRECATED getIndicesWith "Please use indexReaderWith instead." #-}
1294+{-# INLINE getIndicesWith #-}
12491295getIndicesWith :: (Monad m, Unbox a) =>
12501296 (forall b. IO b -> m b) -> D.Stream m Int -> Unfold m (MutArray a) a
12511297getIndicesWith = indexReaderWith
@@ -1261,6 +1307,7 @@ indexReader = indexReaderWith liftIO
12611307
12621308-- XXX DO NOT REMOVE, change the signature to use Stream instead of unfold
12631309{-# DEPRECATED getIndices "Please use indexReader instead." #-}
1310+{-# INLINE getIndices #-}
12641311getIndices :: (MonadIO m, Unbox a) => Stream m Int -> Unfold m (MutArray a) a
12651312getIndices = indexReader
12661313
@@ -1557,7 +1604,7 @@ chunksOfAs ps n (D.Stream step state) =
15571604--
15581605-- Same as the following but may be more efficient:
15591606--
1560−-- >>> chunksOf n = Stream.foldMany (MutArray.writeN n)
1607+-- >>> chunksOf n = Stream.foldMany (MutArray.createOf n)
15611608--
15621609-- /Pre-release/
15631610{-# INLINE_NORMAL chunksOf #-}
@@ -1566,14 +1613,14 @@ chunksOf :: forall m a. (MonadIO m, Unbox a)
15661613-- XXX the idiomatic implementation leads to large regression in the D.reverse'
15671614-- benchmark. It seems it has difficulty producing optimized code when
15681615-- converting to StreamK. Investigate GHC optimizations.
1569−-- chunksOf n = D.foldMany (writeN n)
1616+-- chunksOf n = D.foldMany (createOf n)
15701617chunksOf = chunksOfAs Unpinned
15711618
15721619-- | Like 'chunksOf' but creates pinned arrays.
15731620{-# INLINE_NORMAL pinnedChunksOf #-}
15741621pinnedChunksOf :: forall m a. (MonadIO m, Unbox a)
15751622 => Int -> D.Stream m a -> D.Stream m (MutArray a)
1576−-- pinnedChunksOf n = D.foldMany (pinnedWriteN n)
1623+-- pinnedChunksOf n = D.foldMany (pinnedCreateOf n)
15771624pinnedChunksOf = chunksOfAs Pinned
15781625
15791626-- | When we are buffering a stream of unknown size into an array we do not
@@ -1636,6 +1683,7 @@ concat (D.Stream step state) = D.Stream step' (OuterLoop state)
16361683 return $ D.Yield x (InnerLoop st contents (INDEX_NEXT(p,a)) end)
16371684
16381685{-# DEPRECATED flattenArrays "Please use \"unfoldMany reader\" instead." #-}
1686+{-# INLINE flattenArrays #-}
16391687flattenArrays :: forall m a. (MonadIO m, Unbox a)
16401688 => D.Stream m (MutArray a) -> D.Stream m a
16411689flattenArrays = concat
@@ -1672,6 +1720,7 @@ concatRev (D.Stream step state) = D.Stream step' (OuterLoop state)
16721720 return $ D.Yield x (InnerLoop st contents cur start)
16731721
16741722{-# DEPRECATED flattenArraysRev "Please use \"unfoldMany readerRev\" instead." #-}
1723+{-# INLINE flattenArraysRev #-}
16751724flattenArraysRev :: forall m a. (MonadIO m, Unbox a)
16761725 => D.Stream m (MutArray a) -> D.Stream m a
16771726flattenArraysRev = concatRev
@@ -1903,7 +1952,7 @@ foldr f z arr = D.foldr f z $ read arr
19031952
19041953-- XXX Keep the bound intact to not lose any free space? Perf impact?
19051954
1906−-- | @writeAppendNUnsafe n arr@ appends up to @n@ input items to the supplied
1955+-- | @unsafeAppendN n arr@ appends up to @n@ input items to the supplied
19071956-- array.
19081957--
19091958-- Unsafe: Do not drive the fold beyond @n@ elements, it will lead to memory
@@ -1912,13 +1961,12 @@ foldr f z arr = D.foldr f z $ read arr
19121961-- Any free space left in the array after appending @n@ elements is lost.
19131962--
19141963-- /Internal/
1915−{-# INLINE_NORMAL writeAppendNUnsafe #-}
1916−writeAppendNUnsafe :: forall m a. (MonadIO m, Unbox a) =>
1964+{-# INLINE_NORMAL unsafeAppendN #-}
1965+unsafeAppendN :: forall m a. (MonadIO m, Unbox a) =>
19171966 Int
19181967 -> m (MutArray a)
19191968 -> Fold m a (MutArray a)
1920−writeAppendNUnsafe n action =
1921− fmap fromArrayUnsafe $ FL.foldlM' step initial
1969+unsafeAppendN n action = fmap fromArrayUnsafe $ FL.foldlM' step initial
19221970
19231971 where
19241972
@@ -1931,7 +1979,7 @@ writeAppendNUnsafe n action =
19311979 -- otherwise we lose that space.
19321980 arr1 <-
19331981 if free < needed
1934− then noinline reallocWith "writeAppendNUnsafeWith" (+ needed) needed arr
1982+ then noinline reallocWith "unsafeAppendN" (+ needed) needed arr
19351983 else return arr
19361984 return $ toArrayUnsafe arr1
19371985
@@ -1939,30 +1987,51 @@ writeAppendNUnsafe n action =
19391987 liftIO $ pokeAt end contents x
19401988 return $ ArrayUnsafe contents start (INDEX_NEXT(end,a))
19411989
1990+{-# DEPRECATED writeAppendNUnsafe "Please use unsafeAppendN instead." #-}
1991+{-# INLINE writeAppendNUnsafe #-}
1992+writeAppendNUnsafe :: forall m a. (MonadIO m, Unbox a) =>
1993+ Int
1994+ -> m (MutArray a)
1995+ -> Fold m a (MutArray a)
1996+writeAppendNUnsafe = unsafeAppendN
1997+
19421998-- | Append @n@ elements to an existing array. Any free space left in the array
19431999-- after appending @n@ elements is lost.
19442000--
1945−-- >>> writeAppendN n initial = Fold.take n (MutArray.writeAppendNUnsafe n initial)
2001+-- >>> appendN n initial = Fold.take n (MutArray.unsafeAppendN n initial)
19462002--
1947−{-# INLINE_NORMAL writeAppendN #-}
2003+{-# INLINE_NORMAL appendN #-}
2004+appendN :: forall m a. (MonadIO m, Unbox a) =>
2005+ Int -> m (MutArray a) -> Fold m a (MutArray a)
2006+appendN n initial = FL.take n (unsafeAppendN n initial)
2007+
2008+-- XXX Deprecate in major
2009+-- {-# DEPRECATED writeAppendN "Please use appendN instead." #-}
2010+{-# INLINE writeAppendN #-}
19482011writeAppendN :: forall m a. (MonadIO m, Unbox a) =>
19492012 Int -> m (MutArray a) -> Fold m a (MutArray a)
1950−writeAppendN n initial = FL.take n (writeAppendNUnsafe n initial)
2013+writeAppendN = appendN
19512014
1952−-- | @writeAppendWith realloc action@ mutates the array generated by @action@ to
2015+-- | @appendWith realloc action@ mutates the array generated by @action@ to
19532016-- append the input stream. If there is no reserved space available in the
19542017-- array it is reallocated to a size in bytes determined by @realloc oldSize@,
19552018-- where @oldSize@ is the current size of the array in bytes.
19562019--
19572020-- Note that the returned array may be a mutated version of original array.
19582021--
1959−-- >>> writeAppendWith sizer = Fold.foldlM' (MutArray.snocWith sizer)
2022+-- >>> appendWith sizer = Fold.foldlM' (MutArray.snocWith sizer)
19602023--
19612024-- /Pre-release/
2025+{-# INLINE appendWith #-}
2026+appendWith :: forall m a. (MonadIO m, Unbox a) =>
2027+ (Int -> Int) -> m (MutArray a) -> Fold m a (MutArray a)
2028+appendWith sizer = FL.foldlM' (snocWith sizer)
2029+
2030+{-# DEPRECATED writeAppendWith "Please use appendWith instead." #-}
19622031{-# INLINE writeAppendWith #-}
19632032writeAppendWith :: forall m a. (MonadIO m, Unbox a) =>
19642033 (Int -> Int) -> m (MutArray a) -> Fold m a (MutArray a)
1965−writeAppendWith sizer = FL.foldlM' (snocWith sizer)
2034+writeAppendWith = appendWith
19662035
19672036-- | @append action@ mutates the array generated by @action@ to append the
19682037-- input stream. If there is no reserved space available in the array it is
@@ -1970,26 +2039,33 @@ writeAppendWith sizer = FL.foldlM' (snocWith sizer)
19702039--
19712040-- Note that the returned array may be a mutated version of original array.
19722041--
1973−-- >>> writeAppend = MutArray.writeAppendWith (* 2)
2042+-- >>> append = MutArray.appendWith (* 2)
19742043--
2044+{-# INLINE append #-}
2045+append :: forall m a. (MonadIO m, Unbox a) =>
2046+ m (MutArray a) -> Fold m a (MutArray a)
2047+append = appendWith (* 2)
2048+
2049+-- XXX Deprecate in major
2050+-- {-# DEPRECATED writeAppend "Please use append instead." #-}
19752051{-# INLINE writeAppend #-}
19762052writeAppend :: forall m a. (MonadIO m, Unbox a) =>
19772053 m (MutArray a) -> Fold m a (MutArray a)
1978−writeAppend = writeAppendWith (* 2)
2054+writeAppend = append
19792055
19802056-- XXX We can carry bound as well in the state to make sure we do not lose the
19812057-- remaining capacity. Need to check perf impact.
19822058--
1983−-- | Like 'writeNUnsafe' but takes a new array allocator @alloc size@ function
1984−-- as argument.
2059+-- | Like 'unsafeCreateOf' but takes a new array allocator @alloc size@
2060+-- function as argument.
19852061--
1986−-- >>> writeNWithUnsafe alloc n = MutArray.writeAppendNUnsafe (alloc n) n
2062+-- >>> unsafeCreateOfWith alloc n = MutArray.unsafeAppendN (alloc n) n
19872063--
19882064-- /Pre-release/
1989−{-# INLINE_NORMAL writeNWithUnsafe #-}
1990−writeNWithUnsafe :: forall m a. (MonadIO m, Unbox a)
2065+{-# INLINE_NORMAL unsafeCreateOfWith #-}
2066+unsafeCreateOfWith :: forall m a. (MonadIO m, Unbox a)
19912067 => (Int -> m (MutArray a)) -> Int -> Fold m a (MutArray a)
1992−writeNWithUnsafe alloc n = fromArrayUnsafe <$> FL.foldlM' step initial
2068+unsafeCreateOfWith alloc n = fromArrayUnsafe <$> FL.foldlM' step initial
19932069
19942070 where
19952071
@@ -2000,40 +2076,64 @@ writeNWithUnsafe alloc n = fromArrayUnsafe <$> FL.foldlM' step initial
20002076 return
20012077 $ ArrayUnsafe contents start (INDEX_NEXT(end,a))
20022078
2079+{-# DEPRECATED writeNWithUnsafe "Please use unsafeCreateOfWith instead." #-}
2080+{-# INLINE writeNWithUnsafe #-}
2081+writeNWithUnsafe :: forall m a. (MonadIO m, Unbox a)
2082+ => (Int -> m (MutArray a)) -> Int -> Fold m a (MutArray a)
2083+writeNWithUnsafe = unsafeCreateOfWith
2084+
20032085{-# INLINE_NORMAL writeNUnsafeAs #-}
20042086writeNUnsafeAs :: forall m a. (MonadIO m, Unbox a)
20052087 => PinnedState -> Int -> Fold m a (MutArray a)
2006−writeNUnsafeAs ps = writeNWithUnsafe (newAs ps)
2088+writeNUnsafeAs ps = unsafeCreateOfWith (newAs ps)
20072089
2008−-- | Like 'writeN' but does not check the array bounds when writing. The fold
2090+-- | Like 'createOf' but does not check the array bounds when writing. The fold
20092091-- driver must not call the step function more than 'n' times otherwise it will
20102092-- corrupt the memory and crash. This function exists mainly because any
20112093-- conditional in the step function blocks fusion causing 10x performance
20122094-- slowdown.
20132095--
2014−-- >>> writeNUnsafe = MutArray.writeNWithUnsafe MutArray.new
2096+-- >>> unsafeCreateOf = MutArray.unsafeCreateOfWith MutArray.emptyOf
20152097--
2016−{-# INLINE_NORMAL writeNUnsafe #-}
2098+{-# INLINE_NORMAL unsafeCreateOf #-}
2099+unsafeCreateOf :: forall m a. (MonadIO m, Unbox a)
2100+ => Int -> Fold m a (MutArray a)
2101+unsafeCreateOf = writeNUnsafeAs Unpinned
2102+
2103+{-# DEPRECATED writeNUnsafe "Please use unsafeCreateOf instead." #-}
2104+{-# INLINE writeNUnsafe #-}
20172105writeNUnsafe :: forall m a. (MonadIO m, Unbox a)
20182106 => Int -> Fold m a (MutArray a)
2019−writeNUnsafe = writeNUnsafeAs Unpinned
2107+writeNUnsafe = unsafeCreateOf
20202108
2021−-- | Like 'writeNUnsafe' but creates a pinned array.
2022−{-# INLINE_NORMAL pinnedWriteNUnsafe #-}
2109+-- | Like 'unsafeCreateOf' but creates a pinned array.
2110+{-# INLINE_NORMAL unsafePinnedCreateOf #-}
2111+unsafePinnedCreateOf :: forall m a. (MonadIO m, Unbox a)
2112+ => Int -> Fold m a (MutArray a)
2113+unsafePinnedCreateOf = writeNUnsafeAs Pinned
2114+
2115+{-# DEPRECATED pinnedWriteNUnsafe "Please use unsafePinnedCreateOf instead." #-}
2116+{-# INLINE pinnedWriteNUnsafe #-}
20232117pinnedWriteNUnsafe :: forall m a. (MonadIO m, Unbox a)
20242118 => Int -> Fold m a (MutArray a)
2025−pinnedWriteNUnsafe = writeNUnsafeAs Pinned
2119+pinnedWriteNUnsafe = unsafePinnedCreateOf
20262120
2027−-- | @writeNWith alloc n@ folds a maximum of @n@ elements into an array
2121+-- | @createOfWith alloc n@ folds a maximum of @n@ elements into an array
20282122-- allocated using the @alloc@ function.
20292123--
2030−-- >>> writeNWith alloc n = Fold.take n (MutArray.writeNWithUnsafe alloc n)
2031−-- >>> writeNWith alloc n = MutArray.writeAppendN (alloc n) n
2124+-- >>> createOfWith alloc n = Fold.take n (MutArray.unsafeCreateOfWith alloc n)
2125+-- >>> createOfWith alloc n = MutArray.appendN (alloc n) n
20322126--
2033−{-# INLINE_NORMAL writeNWith #-}
2127+{-# INLINE_NORMAL createOfWith #-}
2128+createOfWith :: forall m a. (MonadIO m, Unbox a)
2129+ => (Int -> m (MutArray a)) -> Int -> Fold m a (MutArray a)
2130+createOfWith alloc n = FL.take n (unsafeCreateOfWith alloc n)
2131+
2132+-- {-# DEPRECATED writeNWith "Please use createOfWith instead." #-}
2133+{-# INLINE writeNWith #-}
20342134writeNWith :: forall m a. (MonadIO m, Unbox a)
20352135 => (Int -> m (MutArray a)) -> Int -> Fold m a (MutArray a)
2036−writeNWith alloc n = FL.take n (writeNWithUnsafe alloc n)
2136+writeNWith = createOfWith
20372137
20382138{-# INLINE_NORMAL writeNAs #-}
20392139writeNAs ::
@@ -2041,28 +2141,42 @@ writeNAs ::
20412141 => PinnedState
20422142 -> Int
20432143 -> Fold m a (MutArray a)
2044−writeNAs ps = writeNWith (newAs ps)
2144+writeNAs ps = createOfWith (newAs ps)
20452145
2046−-- | @writeN n@ folds a maximum of @n@ elements from the input stream to an
2146+-- | @createOf n@ folds a maximum of @n@ elements from the input stream to an
20472147-- 'MutArray'.
20482148--
2049−-- >>> writeN = MutArray.writeNWith MutArray.new
2050−-- >>> writeN n = Fold.take n (MutArray.writeNUnsafe n)
2051−-- >>> writeN n = MutArray.writeAppendN n (MutArray.new n)
2149+-- >>> createOf = MutArray.createOfWith MutArray.new
2150+-- >>> createOf n = Fold.take n (MutArray.unsafeCreateOf n)
2151+-- >>> createOf n = MutArray.appendN n (MutArray.emptyOf n)
20522152--
2053−{-# INLINE_NORMAL writeN #-}
2153+{-# INLINE_NORMAL createOf #-}
2154+createOf :: forall m a. (MonadIO m, Unbox a) => Int -> Fold m a (MutArray a)
2155+createOf = writeNAs Unpinned
2156+
2157+-- XXX Deprecate in major
2158+-- {-# DEPRECATED writeN "Please use createOf instead." #-}
2159+{-# INLINE writeN #-}
20542160writeN :: forall m a. (MonadIO m, Unbox a) => Int -> Fold m a (MutArray a)
2055−writeN = writeNAs Unpinned
2161+writeN = createOf
20562162
2057−-- | Like 'writeN' but creates a pinned array.
2058−{-# INLINE_NORMAL pinnedWriteN #-}
2163+-- | Like 'createOf' but creates a pinned array.
2164+{-# INLINE_NORMAL pinnedCreateOf #-}
2165+pinnedCreateOf ::
2166+ forall m a. (MonadIO m, Unbox a)
2167+ => Int
2168+ -> Fold m a (MutArray a)
2169+pinnedCreateOf = writeNAs Pinned
2170+
2171+{-# DEPRECATED pinnedWriteN "Please use pinnedCreateOf instead." #-}
2172+{-# INLINE pinnedWriteN #-}
20592173pinnedWriteN ::
20602174 forall m a. (MonadIO m, Unbox a)
20612175 => Int
20622176 -> Fold m a (MutArray a)
2063−pinnedWriteN = writeNAs Pinned
2177+pinnedWriteN = pinnedCreateOf
20642178
2065−-- | Like writeNWithUnsafe but writes the array in reverse order.
2179+-- | Like unsafeCreateOfWith but writes the array in reverse order.
20662180--
20672181-- /Internal/
20682182{-# INLINE_NORMAL writeRevNWithUnsafe #-}
@@ -2083,7 +2197,7 @@ writeRevNWithUnsafe alloc n = fromArrayUnsafe <$> FL.foldlM' step initial
20832197 return
20842198 $ ArrayUnsafe contents ptr end
20852199
2086−-- | Like writeNWith but writes the array in reverse order.
2200+-- | Like createOfWith but writes the array in reverse order.
20872201--
20882202-- /Internal/
20892203{-# INLINE_NORMAL writeRevNWith #-}
@@ -2091,31 +2205,36 @@ writeRevNWith :: forall m a. (MonadIO m, Unbox a)
20912205 => (Int -> m (MutArray a)) -> Int -> Fold m a (MutArray a)
20922206writeRevNWith alloc n = FL.take n (writeRevNWithUnsafe alloc n)
20932207
2094−-- | Like writeN but writes the array in reverse order.
2208+-- | Like 'createOf' but writes the array in reverse order.
20952209--
20962210-- /Pre-release/
2097−{-# INLINE_NORMAL writeRevN #-}
2211+{-# INLINE_NORMAL revCreateOf #-}
2212+revCreateOf :: forall m a. (MonadIO m, Unbox a) => Int -> Fold m a (MutArray a)
2213+revCreateOf = writeRevNWith new
2214+
2215+{-# DEPRECATED writeRevN "Please use revCreateOf instead." #-}
2216+{-# INLINE writeRevN #-}
20982217writeRevN :: forall m a. (MonadIO m, Unbox a) => Int -> Fold m a (MutArray a)
2099−writeRevN = writeRevNWith new
2218+writeRevN = revCreateOf
21002219
21012220-- | @pinnedWriteNAligned align n@ folds a maximum of @n@ elements from the
21022221-- input stream to a 'MutArray' aligned to the given size.
21032222--
2104−-- >>> pinnedWriteNAligned align = MutArray.writeNWith (MutArray.pinnedNewAligned align)
2105−-- >>> pinnedWriteNAligned align n = MutArray.writeAppendN n (MutArray.pinnedNewAligned align n)
2223+-- >>> pinnedWriteNAligned align = MutArray.createOfWith (MutArray.pinnedNewAligned align)
2224+-- >>> pinnedWriteNAligned align n = MutArray.appendN n (MutArray.pinnedNewAligned align n)
21062225--
21072226-- /Pre-release/
21082227--
21092228{-# INLINE_NORMAL pinnedWriteNAligned #-}
21102229pinnedWriteNAligned :: forall m a. (MonadIO m, Unbox a)
21112230 => Int -> Int -> Fold m a (MutArray a)
2112−pinnedWriteNAligned align = writeNWith (pinnedNewAligned align)
2231+pinnedWriteNAligned align = createOfWith (pinnedNewAligned align)
21132232
21142233-- XXX Buffer to a list instead?
21152234
21162235-- | Buffer a stream into a stream of arrays.
21172236--
2118−-- >>> buildChunks n = Fold.many (MutArray.writeN n) Fold.toStreamK
2237+-- >>> buildChunks n = Fold.many (MutArray.createOf n) Fold.toStreamK
21192238--
21202239-- Breaking an array into an array stream can be useful to consume a large
21212240-- array sequentially such that memory of the array is released incrementatlly.
@@ -2127,9 +2246,10 @@ pinnedWriteNAligned align = writeNWith (pinnedNewAligned align)
21272246{-# INLINE_NORMAL buildChunks #-}
21282247buildChunks :: (MonadIO m, Unbox a) =>
21292248 Int -> Fold m a (StreamK n (MutArray a))
2130−buildChunks n = FL.many (writeN n) FL.toStreamK
2249+buildChunks n = FL.many (createOf n) FL.toStreamK
21312250
21322251{-# DEPRECATED writeChunks "Please use buildChunks instead." #-}
2252+{-# INLINE writeChunks #-}
21332253writeChunks :: (MonadIO m, Unbox a) =>
21342254 Int -> Fold m a (StreamK n (MutArray a))
21352255writeChunks = buildChunks
@@ -2137,14 +2257,14 @@ writeChunks = buildChunks
21372257{-# INLINE_NORMAL writeWithAs #-}
21382258writeWithAs :: forall m a. (MonadIO m, Unbox a)
21392259 => PinnedState -> Int -> Fold m a (MutArray a)
2140−-- writeWithAs ps n = FL.rmapM rightSize $ writeAppendWith (* 2) (newAs ps n)
2260+-- writeWithAs ps n = FL.rmapM rightSize $ appendWith (* 2) (newAs ps n)
21412261writeWithAs ps elemCount =
21422262 FL.rmapM extract $ FL.foldlM' step initial
21432263
21442264 where
21452265
21462266 initial = do
2147− when (elemCount < 0) $ error "writeWith: elemCount is negative"
2267+ when (elemCount < 0) $ error "createWith: elemCount is negative"
21482268 newAs ps elemCount
21492269
21502270 step arr@(MutArray _ start end bound) x
@@ -2157,9 +2277,9 @@ writeWithAs ps elemCount =
21572277
21582278 extract = liftIO . rightSize
21592279
2160−-- XXX Compare writeWith with fromStreamD which uses an array of streams
2280+-- XXX Compare createWith with fromStreamD which uses an array of streams
21612281-- implementation. We can write this using buildChunks above if that is faster.
2162−-- If writeWith is faster then we should use that to implement
2282+-- If createWith is faster then we should use that to implement
21632283-- fromStreamD.
21642284--
21652285-- XXX The realloc based implementation needs to make one extra copy if we use
@@ -2174,39 +2294,56 @@ writeWithAs ps elemCount =
21742294-- XXX check if GHC's memory allocator is efficient enough. We can try the C
21752295-- malloc to compare against.
21762296
2177−-- | @writeWith minCount@ folds the whole input to a single array. The array
2297+-- | @createWith minCount@ folds the whole input to a single array. The array
21782298-- starts at a size big enough to hold minCount elements, the size is doubled
21792299-- every time the array needs to be grown.
21802300--
21812301-- /Caution! Do not use this on infinite streams./
21822302--
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)
2303+-- >>> f n = MutArray.appendWith (* 2) (MutArray.emptyOf n)
2304+-- >>> createWith n = Fold.rmapM MutArray.rightSize (f n)
2305+-- >>> createWith n = Fold.rmapM MutArray.fromChunksK (MutArray.buildChunks n)
21862306--
21872307-- /Pre-release/
2188−{-# INLINE_NORMAL writeWith #-}
2308+{-# INLINE_NORMAL createWith #-}
2309+createWith :: forall m a. (MonadIO m, Unbox a)
2310+ => Int -> Fold m a (MutArray a)
2311+-- createWith n = FL.rmapM rightSize $ appendWith (* 2) (emptyOf n)
2312+createWith = writeWithAs Unpinned
2313+
2314+{-# DEPRECATED writeWith "Please use createWith instead." #-}
2315+{-# INLINE writeWith #-}
21892316writeWith :: forall m a. (MonadIO m, Unbox a)
21902317 => Int -> Fold m a (MutArray a)
2191−-- writeWith n = FL.rmapM rightSize $ writeAppendWith (* 2) (new n)
2192−writeWith = writeWithAs Unpinned
2318+writeWith = createWith
21932319
21942320-- | Fold the whole input to a single array.
21952321--
2196−-- Same as 'writeWith' using an initial array size of 'arrayChunkBytes' bytes
2322+-- Same as 'createWith' using an initial array size of 'arrayChunkBytes' bytes
21972323-- rounded up to the element size.
21982324--
21992325-- /Caution! Do not use this on infinite streams./
22002326--
2327+{-# INLINE create #-}
2328+create :: forall m a. (MonadIO m, Unbox a) => Fold m a (MutArray a)
2329+create = createWith (allocBytesToElemCount (undefined :: a) arrayChunkBytes)
2330+
2331+-- XXX Deprecate in major
2332+-- {-# DEPRECATED write "Please use create instead." #-}
22012333{-# INLINE write #-}
22022334write :: forall m a. (MonadIO m, Unbox a) => Fold m a (MutArray a)
2203−write = writeWith (allocBytesToElemCount (undefined :: a) arrayChunkBytes)
2335+write = create
22042336
2205−-- | Like 'write' but creates a pinned array.
2337+-- | Like 'create' but creates a pinned array.
2338+{-# INLINE pinnedCreate #-}
2339+pinnedCreate :: forall m a. (MonadIO m, Unbox a) => Fold m a (MutArray a)
2340+pinnedCreate =
2341+ writeWithAs Pinned (allocBytesToElemCount (undefined :: a) arrayChunkBytes)
2342+
2343+{-# DEPRECATED pinnedWrite "Please use pinnedCreate instead." #-}
22062344{-# INLINE pinnedWrite #-}
22072345pinnedWrite :: forall m a. (MonadIO m, Unbox a) => Fold m a (MutArray a)
2208−pinnedWrite =
2209− writeWithAs Pinned (allocBytesToElemCount (undefined :: a) arrayChunkBytes)
2346+pinnedWrite = pinnedCreate
22102347
22112348-------------------------------------------------------------------------------
22122349-- construct from streams, known size
@@ -2226,17 +2363,18 @@ fromStreamDNAs ps limit str = do
22262363 liftIO $ pokeAt ptr arrContents x
22272364 return $ INDEX_NEXT(ptr,a)
22282365
2229−-- | Use the 'writeN' fold instead.
2366+-- | Use the 'createOf' fold instead.
22302367--
2231−-- >>> fromStreamN n = Stream.fold (MutArray.writeN n)
2368+-- >>> fromStreamN n = Stream.fold (MutArray.createOf n)
22322369--
22332370{-# INLINE_NORMAL fromStreamN #-}
22342371fromStreamN :: forall m a. (MonadIO m, Unbox a)
22352372 => Int -> D.Stream m a -> m (MutArray a)
2236−-- fromStreamDN n = D.fold (writeN n)
2373+-- fromStreamDN n = D.fold (createOf n)
22372374fromStreamN = fromStreamDNAs Unpinned
22382375
22392376{-# DEPRECATED fromStreamDN "Please use fromStreamN instead." #-}
2377+{-# INLINE fromStreamDN #-}
22402378fromStreamDN :: forall m a. (MonadIO m, Unbox a)
22412379 => Int -> D.Stream m a -> m (MutArray a)
22422380fromStreamDN = fromStreamN
@@ -2259,20 +2397,20 @@ pinnedFromListN n xs = fromStreamDNAs Pinned n $ D.fromList xs
22592397-- /Pre-release/
22602398{-# INLINE fromListRevN #-}
22612399fromListRevN :: (MonadIO m, Unbox a) => Int -> [a] -> m (MutArray a)
2262−fromListRevN n xs = D.fold (writeRevN n) $ D.fromList xs
2400+fromListRevN n xs = D.fold (revCreateOf n) $ D.fromList xs
22632401
22642402-- | Convert a pure stream in Identity monad to a mutable array.
22652403{-# INLINABLE fromPureStreamN #-}
22662404fromPureStreamN :: (MonadIO m, Unbox a) =>
22672405 Int -> Stream Identity a -> m (MutArray a)
22682406fromPureStreamN n xs =
2269− D.fold (writeN n) $ D.morphInner (return . runIdentity) xs
2407+ D.fold (createOf n) $ D.morphInner (return . runIdentity) xs
22702408
22712409-- | Convert a pure stream in Identity monad to a mutable array.
22722410{-# INLINABLE fromPureStream #-}
22732411fromPureStream :: (MonadIO m, Unbox a) => Stream Identity a -> m (MutArray a)
22742412fromPureStream xs =
2275− D.fold write $ D.morphInner (return . runIdentity) xs
2413+ D.fold create $ D.morphInner (return . runIdentity) xs
22762414
22772415{-# INLINABLE fromPtrN #-}
22782416fromPtrN :: MonadIO m => Int -> Ptr Word8 -> m (MutArray Word8)
@@ -2356,6 +2494,7 @@ fromChunksK :: (Unbox a, MonadIO m) =>
23562494fromChunksK = fromChunkskAs Unpinned
23572495
23582496{-# DEPRECATED fromArrayStreamK "Please use fromChunksK instead." #-}
2497+{-# INLINE fromArrayStreamK #-}
23592498fromArrayStreamK :: (Unbox a, MonadIO m) =>
23602499 StreamK m (MutArray a) -> m (MutArray a)
23612500fromArrayStreamK = fromChunksK
@@ -2367,7 +2506,7 @@ fromStreamDAs ps m =
23672506 arrayStreamKFromStreamDAs Unpinned m >>= fromChunkskAs ps
23682507
23692508-- | 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
2509+-- single array from a stream of unknown size. 'createOf' is at least twice
23712510-- as efficient when the size is already known.
23722511--
23732512-- Note that if the input stream is too large memory allocation for the array
@@ -2379,19 +2518,19 @@ fromStreamDAs ps m =
23792518fromStream :: (MonadIO m, Unbox a) => Stream m a -> m (MutArray a)
23802519fromStream = fromStreamDAs Unpinned
23812520
2382−-- fromStream (Stream m) = P.fold write m
2521+-- fromStream (Stream m) = P.fold create m
23832522-- CAUTION: a very large number (millions) of arrays can degrade performance
23842523-- due to GC overhead because we need to buffer the arrays before we flatten
23852524-- all the arrays.
23862525--
2387−-- XXX Compare if this is faster or "fold write".
2526+-- XXX Compare if this is faster or "fold create".
23882527--
23892528-- | We could take the approach of doubling the memory allocation on each
23902529-- overflow. This would result in more or less the same amount of copying as in
23912530-- the chunking approach. However, if we have to shrink in the end then it may
23922531-- result in an extra copy of the entire data.
23932532--
2394−-- >>> fromStreamD = StreamD.fold MutArray.write
2533+-- >>> fromStreamD = StreamD.fold MutArray.create
23952534--
23962535{-# INLINE fromStreamD #-}
23972536{-# DEPRECATED fromStreamD "Please use fromStream instead." #-}
@@ -2421,6 +2560,10 @@ fromListRev xs = fromListRevN (Prelude.length xs) xs
24212560-- Cloning
24222561-------------------------------------------------------------------------------
24232562
2563+-- Arrays are aligned on 64-bit boundaries. The fastest way to copy an array is
2564+-- to unsafeCast it to Word64, read it, write it to Word64 array and unsafeCast
2565+-- it again. We can use SIMD read/write as well.
2566+
24242567{-# INLINE cloneAs #-}
24252568cloneAs ::
24262569 ( MonadIO m
@@ -2512,7 +2655,7 @@ spliceWith :: forall m a. (MonadIO m, Unbox a) =>
25122655 (Int -> Int -> Int) -> MutArray a -> MutArray a -> m (MutArray a)
25132656spliceWith sizer dst@(MutArray _ start end bound) src = do
25142657{-
2515− let f = writeAppendWith (`sizer` byteLength src) (return dst)
2658+ let f = appendWith (`sizer` byteLength src) (return dst)
25162659 in D.fold f (toStreamD src)
25172660-}
25182661 assert (end <= bound) (return ())
@@ -2687,9 +2830,13 @@ cast arr =
26872830-- guarantees that unsafe calls will be performed in the calling thread. Making
26882831-- it safe to pass heap-allocated objects to unsafe functions.
26892832
2690−-- Should we just name it asPtr, the unsafety is implicit for any pointer
2833+-- XXX Should we just name it asPtr, the unsafety is implicit for any pointer
26912834-- operations. And we are safe from Haskell perspective because we will be
26922835-- pinning the memory.
2836+--
2837+-- XXX we cannot pass the length of the ptr here as in some cases it may not be
2838+-- available e.g. a null terminated C string. However, we can create another
2839+-- flavor of the API e.g. asPtrN.
26932840
26942841-- | Use a @MutArray a@ as @Ptr a@. This is useful when we want to pass an
26952842-- array as a pointer to some operating system call or to a "safe" FFI call.