@@ -1,12 +1,26 @@
1+{-# LANGUAGE CPP #-}
12{-# LANGUAGE UnboxedTuples #-}
23-- |
3−-- Module : Streamly.Internal.Data.MutArray.Mut.Type
4+-- Module : Streamly.Internal.Data.Array.Mut.Type
45-- Copyright : (c) 2020 Composewell Technologies
56-- License : BSD3-3-Clause
67-- Maintainer : streamly@composewell.com
78-- Stability : experimental
89-- Portability : GHC
910--
11+-- Pinned and unpinned mutable array for 'Unboxed' types. Fulfils the following
12+-- goals:
13+--
14+-- * Random access (array)
15+-- * Efficient storage (unboxed)
16+-- * Performance (unboxed access)
17+-- * Performance - in-place operations (mutable)
18+-- * Performance - GC (pinned, mutable)
19+-- * interfacing with OS (pinned)
20+--
21+-- Stream and Fold APIs allow easy, efficient and convenient operations on
22+-- arrays.
23+--
1024-- Mutable arrays and file system files are quite similar, they can grow and
1125-- their content is mutable. Therefore, both have similar APIs as well. We
1226-- strive to keep the API consistent for both. Ideally, you should be able to
@@ -205,10 +219,6 @@ module Streamly.Internal.Data.Array.Mut.Type
205219 )
206220where
207221
208−-- Notes:
209−-- When we use a purely lazy Monad like Identity, we need to force ordering of
210−-- some actions for correctness.
211−
212222#include "assert.hs"
213223#include "inline.hs"
214224#include "ArrayMacros.h"
@@ -259,13 +269,7 @@ import qualified Prelude
259269import Prelude hiding
260270 (length, foldr, read, unlines, splitAt, reverse, truncate)
261271
262−-- $setup
263−-- >>> :m
264−-- >>> import qualified Streamly.Internal.Data.Array.Mut.Type as MutArray
265−-- >>> import qualified Streamly.Internal.Data.Stream as Stream
266−-- >>> import qualified Streamly.Internal.Data.Stream.StreamD as StreamD
267−-- >>> import qualified Streamly.Internal.Data.Fold as Fold
268−-- >>> import qualified Streamly.Internal.Data.Fold.Type as Fold
272+#include "DocTestDataMutArray.hs"
269273
270274-------------------------------------------------------------------------------
271275-- Foreign helpers
@@ -305,14 +309,12 @@ memcmp p1 p2 len = do
305309
306310-- $arrayNotes
307311--
308−-- We can use an 'Unboxed' constraint in the MutArray type and the constraint can
309−-- be automatically provided to a function that pattern matches on the MutArray
310−-- type. However, it has huge performance cost, so we do not use it.
312+-- We can use an 'Unboxed' constraint in the MutArray type and the constraint
313+-- can be automatically provided to a function that pattern matches on the
314+-- MutArray type. However, it has huge performance cost, so we do not use it.
311315-- Investigate a GHC improvement possiblity.
312316
313−-- XXX Rename the fields to better names.
314−
315−-- | An unboxed, pinned mutable array. An array is created with a given length
317+-- | An unboxed mutable array. An array is created with a given length
316318-- and capacity. Length is the number of valid elements in the array. Capacity
317319-- is the maximum number of elements that the array can be expanded to without
318320-- having to reallocate the memory.
@@ -1520,7 +1522,8 @@ toListFB c n MutArray{..} = go arrStart
15201522
15211523-- XXX Monadic foldr/build fusion?
15221524-- Reference: https://www.researchgate.net/publication/220676509_Monadic_augment_and_generalised_short_cut_fusion
1523−-- | Convert an 'MutArray' into a list.
1525+
1526+-- | Convert a 'MutArray' into a list.
15241527--
15251528{-# INLINE toList #-}
15261529toList :: forall m a. (MonadIO m, Unbox a) => MutArray a -> m [a]
@@ -1813,7 +1816,7 @@ writeRevN :: forall m a. (MonadIO m, Unbox a) => Int -> Fold m a (MutArray a)
18131816writeRevN = writeRevNWith newPinned
18141817
18151818-- | @writeNAligned align n@ folds a maximum of @n@ elements from the input
1816−-- stream to an 'MutArray' aligned to the given size.
1819+-- stream to a 'MutArray' aligned to the given size.
18171820--
18181821-- >>> writeNAligned align = MutArray.writeNWith (MutArray.newAlignedPinned align)
18191822-- >>> writeNAligned align n = MutArray.writeAppendN n (MutArray.newAlignedPinned align n)
@@ -1911,7 +1914,7 @@ write = writeWith (allocBytesToElemCount (undefined :: a) arrayChunkBytes)
19111914
19121915-- | Use the 'writeN' fold instead.
19131916--
1914−-- >>> fromStreamDN n = StreamD.fold (MutArray.writeN n)
1917+-- >>> fromStreamDN n = Stream.fold (MutArray.writeN n)
19151918--
19161919{-# INLINE_NORMAL fromStreamDN #-}
19171920fromStreamDN :: forall m a. (MonadIO m, Unbox a)
@@ -1928,7 +1931,7 @@ fromStreamDN limit str = do
19281931 liftIO $ pokeWith arrContents ptr x
19291932 return $ INDEX_NEXT(ptr,a)
19301933
1931−-- | Create an 'MutArray' from the first N elements of a list. The array is
1934+-- | Create a 'MutArray' from the first N elements of a list. The array is
19321935-- allocated to size N, if the list terminates before N elements then the
19331936-- array may hold less than N elements.
19341937--
@@ -1978,7 +1981,7 @@ fromArrayStreamK as = do
19781981fromStreamD :: (MonadIO m, Unbox a) => D.Stream m a -> m (MutArray a)
19791982fromStreamD m = arrayStreamKFromStreamD m >>= fromArrayStreamK
19801983
1981−-- | Create an 'MutArray' from a list. The list must be of finite size.
1984+-- | Create a 'MutArray' from a list. The list must be of finite size.
19821985--
19831986{-# INLINE fromList #-}
19841987fromList :: (MonadIO m, Unbox a) => [a] -> m (MutArray a)