@@ -22,19 +22,19 @@ module Streamly.Internal.FileSystem.Handle
2222 -- , readUtf8
2323 -- , readLines
2424 -- , readFrames
25− , readInChunksOf
25+ , readRequestsOf
2626
2727 , toStream
28− , toStreamInChunksOf
28+ , toStreamRequestsOf
2929
3030 -- -- * Array Read
3131 -- , readArrayUpto
3232 -- , readArrayOf
33− , readArraysOf
34− , readArrays
33+ , readChunks
34+ , readChunksRequestsOf
3535
36− , toStreamArraysOf
37− , toStreamArrays
36+ , toChunksRequestsOf
37+ , toChunks
3838
3939 -- ** Write to Handle
4040 -- Byte stream write (Folds)
@@ -42,7 +42,7 @@ module Streamly.Internal.FileSystem.Handle
4242 -- , writeUtf8
4343 -- , writeUtf8ByLines
4444 -- , writeByFrames
45− , writeInChunksOf
45+ , writeRequestsOf
4646
4747 -- Byte stream write (Streams)
4848 , fromStream
@@ -50,8 +50,8 @@ module Streamly.Internal.FileSystem.Handle
5050
5151 -- -- * Array Write
5252 , writeArray
53− , writeArrays
54− , writeArraysInChunksOf
53+ , writeChunks
54+ , writeChunksRequestsOf
5555
5656 -- -- * Array stream Write
5757 , fromStreamArrays
@@ -63,18 +63,37 @@ module Streamly.Internal.FileSystem.Handle
6363 -- include disks, files, memory devices and exclude terminals, pipes,
6464 -- sockets and fifos.
6565 --
66+ -- XXX need to decide whether to use readFromStepN style or readFromThenTo
67+ -- style. The latter is consistent with list enumeration. The former may be
68+ -- more unambiguous and it is easier and clearer to specify 0 elements.
69+ --
70+ -- We can also generate the request pattern using a funciton.
71+ --
6672 -- , readIndex
67− -- , readSlice
68− -- , readSliceRev
69− -- , readAt -- read from a given position to th end of file
70− -- , readSliceArrayUpto
71− -- , readSliceArrayOf
73+ -- , readFrom -- read from a given position to the end of file
74+ -- , readFromRev -- read from a given position the beginning of file
75+ -- , readTo -- read from beginning up to the given position
76+ -- , readToRev -- read from end to the given position in file
77+ -- , readFromTo
78+ -- , readFromThenTo
79+
80+ -- , readChunksFrom
81+ -- , readChunksFromTo
82+ -- , readChunksFromToRequestsOf
83+ -- , readChunksFromThenToRequestsOf
7284
7385 -- , writeIndex
74− -- , writeSlice
75− -- , writeSliceRev
76− -- , writeAt -- start writing at the given position
77− -- , writeSliceArray
86+ -- , writeFrom -- start writing at the given position
87+ -- , writeFromRev
88+ -- , writeTo -- write from beginning up to the given position
89+ -- , writeToRev
90+ -- , writeFromTo
91+ -- , writeFromThenTo
92+ --
93+ -- , writeChunksFrom
94+ -- , writeChunksFromTo
95+ -- , writeChunksFromToRequestsOf
96+ -- , writeChunksFromThenToRequestsOf
7897 )
7998where
8099
@@ -145,13 +164,13 @@ readArrayUpto size h = do
145164-- Stream of Arrays IO
146165-------------------------------------------------------------------------------
147166
148−-- | @toStreamArraysOf size h@ reads a stream of arrays from file handle @h@.
167+-- | @toChunksRequestsOf size h@ reads a stream of arrays from file handle @h@.
149168-- The maximum size of a single array is specified by @size@. The actual size
150169-- read may be less than or equal to @size@.
151−{-# INLINABLE _toStreamArraysOf #-}
152−_toStreamArraysOf :: (IsStream t, MonadIO m)
170+{-# INLINABLE _toChunksRequestsOf #-}
171+_toChunksRequestsOf :: (IsStream t, MonadIO m)
153172 => Int -> Handle -> t m (Array Word8)
154−_toStreamArraysOf size h = go
173+_toChunksRequestsOf size h = go
155174 where
156175 -- XXX use cons/nil instead
157176 go = mkStream $ \_ yld _ stp -> do
@@ -160,14 +179,14 @@ _toStreamArraysOf size h = go
160179 then stp
161180 else yld arr go
162181
163−-- | @toStreamArraysOf size handle@ reads a stream of arrays from the file
182+-- | @toChunksRequestsOf size handle@ reads a stream of arrays from the file
164183-- handle @handle@. The maximum size of a single array is limited to @size@.
165184-- The actual size read may be less than or equal to @size@.
166185--
167186-- @since 0.7.0
168−{-# INLINE_NORMAL toStreamArraysOf #-}
169−toStreamArraysOf :: (IsStream t, MonadIO m) => Int -> Handle -> t m (Array Word8)
170−toStreamArraysOf size h = D.fromStreamD (D.Stream step ())
187+{-# INLINE_NORMAL toChunksRequestsOf #-}
188+toChunksRequestsOf :: (IsStream t, MonadIO m) => Int -> Handle -> t m (Array Word8)
189+toChunksRequestsOf size h = D.fromStreamD (D.Stream step ())
171190 where
172191 {-# INLINE_LATE step #-}
173192 step _ _ = do
@@ -179,12 +198,12 @@ toStreamArraysOf size h = D.fromStreamD (D.Stream step ())
179198
180199-- | Unfold the tuple @(size, handle)@ into a stream of 'Word8' arrays. The
181200-- stream consists of arrays representing chunks of data read from the handle.
182−-- The maximum size of a single array is limited to @size@.
201+-- The size of an array in the stream is less than or equal to @size@.
183202--
184203-- @since 0.7.0
185−{-# INLINE_NORMAL readArraysOf #-}
186−readArraysOf :: MonadIO m => Unfold m (Int, Handle) (Array Word8)
187−readArraysOf = Unfold step return
204+{-# INLINE_NORMAL readChunksRequestsOf #-}
205+readChunksRequestsOf :: MonadIO m => Unfold m (Int, Handle) (Array Word8)
206+readChunksRequestsOf = Unfold step return
188207 where
189208 {-# INLINE_LATE step #-}
190209 step (size, h) = do
@@ -196,25 +215,28 @@ readArraysOf = Unfold step return
196215
197216-- XXX read 'Array a' instead of Word8
198217--
199−-- | @toStreamArrays handle@ reads a stream of arrays from the specified file
218+-- | @toChunks handle@ reads a stream of arrays from the specified file
200219-- handle. The maximum size of a single array is limited to
201220-- @defaultChunkSize@. The actual size read may be less than or equal to
202221-- @defaultChunkSize@.
203222--
204−-- > toStreamArrays = toStreamArraysOf defaultChunkSize
223+-- > toChunks = toChunksRequestsOf defaultChunkSize
205224--
206225-- @since 0.7.0
207−{-# INLINE toStreamArrays #-}
208−toStreamArrays :: (IsStream t, MonadIO m) => Handle -> t m (Array Word8)
209−toStreamArrays = toStreamArraysOf defaultChunkSize
226+{-# INLINE toChunks #-}
227+toChunks :: (IsStream t, MonadIO m) => Handle -> t m (Array Word8)
228+toChunks = toChunksRequestsOf defaultChunkSize
210229
211−-- | Unfolds a handle into a stream of 'Word8' arrays. The maximum size of a
212−-- single array is limited to @defaultChunkSize@.
230+-- | Unfolds a handle into a stream of 'Word8' arrays. Requests to the IO
231+-- device are performed using a buffer of size
232+-- 'Streamly.Internal.Memory.Array.Types.defaultChunkSize'. The
233+-- size of arrays in the resulting stream are therefore less than or equal to
234+-- 'Streamly.Internal.Memory.Array.Types.defaultChunkSize'.
213235--
214236-- @since 0.7.0
215−{-# INLINE readArrays #-}
216−readArrays :: MonadIO m => Unfold m Handle (Array Word8)
217−readArrays = UF.supplyFirst readArraysOf defaultChunkSize
237+{-# INLINE readChunks #-}
238+readChunks :: MonadIO m => Unfold m Handle (Array Word8)
239+readChunks = UF.supplyFirst readChunksRequestsOf defaultChunkSize
218240
219241-------------------------------------------------------------------------------
220242-- Read File to Stream
@@ -224,40 +246,41 @@ readArrays = UF.supplyFirst readArraysOf defaultChunkSize
224246-- read requests at the same time. For serial case we can use async IO. We can
225247-- also control the read throughput in mbps or IOPS.
226248
227−-- | @readInChunksOf@ unfolds @(chunksize, handle)@ into a byte stream, reads
228−-- are performed in chunks of up to @chunkSize@.
249+-- | Unfolds the tuple @(chunksize, handle)@ into a byte stream, read requests
250+-- to the IO device are performed using buffers of @chunkSize@.
229251--
230252-- @since 0.7.0
231−{-# INLINE readInChunksOf #-}
232−readInChunksOf :: MonadIO m => Unfold m (Int, Handle) Word8
233−readInChunksOf = UF.concat readArraysOf A.read
253+{-# INLINE readRequestsOf #-}
254+readRequestsOf :: MonadIO m => Unfold m (Int, Handle) Word8
255+readRequestsOf = UF.concat readChunksRequestsOf A.read
234256
235−-- | @toStreamInChunksOf chunkSize handle@ reads a byte stream from a file
257+-- | @toStreamRequestsOf chunkSize handle@ reads a byte stream from a file
236258-- handle, reads are performed in chunks of up to @chunkSize@.
237259--
238260-- /Internal/
239−{-# INLINE toStreamInChunksOf #-}
240−toStreamInChunksOf :: (IsStream t, MonadIO m) => Int -> Handle -> t m Word8
241−toStreamInChunksOf chunkSize h = AS.concat $ toStreamArraysOf chunkSize h
261+{-# INLINE toStreamRequestsOf #-}
262+toStreamRequestsOf :: (IsStream t, MonadIO m) => Int -> Handle -> t m Word8
263+toStreamRequestsOf chunkSize h = AS.concat $ toChunksRequestsOf chunkSize h
242264
243265-- TODO
244266-- Generate a stream of elements of the given type from a file 'Handle'.
245267-- read :: (IsStream t, MonadIO m, Storable a) => Handle -> t m a
246268--
247−-- > read = 'readInChunksOf' A.defaultChunkSize
248−-- | Unfolds a file handle into a byte stream.
269+-- | Unfolds a file handle into a byte stream. IO requests to the device are
270+-- performed in sizes of
271+-- 'Streamly.Internal.Memory.Array.Types.defaultChunkSize'.
249272--
250273-- @since 0.7.0
251274{-# INLINE read #-}
252275read :: MonadIO m => Unfold m Handle Word8
253−read = UF.supplyFirst readInChunksOf defaultChunkSize
276+read = UF.supplyFirst readRequestsOf defaultChunkSize
254277
255278-- | Generate a byte stream from a file 'Handle'.
256279--
257280-- /Internal/
258281{-# INLINE toStream #-}
259282toStream :: (IsStream t, MonadIO m) => Handle -> t m Word8
260−toStream = AS.concat . toStreamArrays
283+toStream = AS.concat . toChunks
261284
262285-------------------------------------------------------------------------------
263286-- Writing
@@ -316,10 +339,10 @@ fromStreamInChunksOf :: MonadIO m => Int -> Handle -> SerialT m Word8 -> m ()
316339fromStreamInChunksOf n h m = fromStreamArrays h $ S.arraysOf n m
317340-- fromStreamInChunksOf n h m = fromStreamArrays h $ AS.arraysOf n m
318341
319−-- > write = 'writeInChunksOf' A.defaultChunkSize
342+-- > write = 'writeRequestsOf' A.defaultChunkSize
320343--
321344-- | Write a byte stream to a file handle. Accumulates the input in chunks of
322−-- up to 'A.defaultChunkSize' before writing.
345+-- up to 'Streamly.Internal.Memory.Array.Types.defaultChunkSize' before writing.
323346--
324347-- NOTE: This may perform better than the 'write' fold, you can try this if you
325348-- need some extra perf boost.
@@ -329,24 +352,25 @@ fromStreamInChunksOf n h m = fromStreamArrays h $ S.arraysOf n m
329352fromStream :: MonadIO m => Handle -> SerialT m Word8 -> m ()
330353fromStream = fromStreamInChunksOf defaultChunkSize
331354
332−-- | Write a stream of arrays to a handle.
355+-- | Write a stream of arrays to a handle. Each array in the stream is written
356+-- to the device as a separate IO request.
333357--
334358-- @since 0.7.0
335−{-# INLINE writeArrays #-}
336−writeArrays :: (MonadIO m, Storable a) => Handle -> Fold m (Array a) ()
337−writeArrays h = FL.drainBy (liftIO . writeArray h)
359+{-# INLINE writeChunks #-}
360+writeChunks :: (MonadIO m, Storable a) => Handle -> Fold m (Array a) ()
361+writeChunks h = FL.drainBy (liftIO . writeArray h)
338362
339−-- | @writeArraysInChunksOf chunkSize handle@ writes a stream of arrays
363+-- | @writeChunksRequestsOf chunkSize handle@ writes a stream of arrays
340364-- to @handle@ after coalescing the adjacent arrays in chunks of @chunkSize@.
341365-- We never split an array, if a single array is bigger than the specified size
342366-- it emitted as it is. Multiple arrays are coalesed as long as the total size
343367-- remains below the specified size.
344368--
345369-- @since 0.7.0
346−{-# INLINE writeArraysInChunksOf #-}
347−writeArraysInChunksOf :: (MonadIO m, Storable a)
370+{-# INLINE writeChunksRequestsOf #-}
371+writeChunksRequestsOf :: (MonadIO m, Storable a)
348372 => Int -> Handle -> Fold m (Array a) ()
349−writeArraysInChunksOf n h = lpackArraysChunksOf n (writeArrays h)
373+writeChunksRequestsOf n h = lpackArraysChunksOf n (writeChunks h)
350374
351375-- GHC buffer size dEFAULT_FD_BUFFER_SIZE=8192 bytes.
352376--
@@ -356,24 +380,25 @@ writeArraysInChunksOf n h = lpackArraysChunksOf n (writeArrays h)
356380-- do not want buffering to occur at GHC level as well. Same thing applies to
357381-- writes as well.
358382
359−-- | @writeInChunksOf chunkSize handle@ writes the input stream to @handle@ in
360−-- chunks of @chunkSize@. A write is performed to the IO device as soon as we
361−-- collect the required input size.
383+-- | @writeRequestsOf reqSize handle@ writes the input stream to @handle@.
384+-- Bytes in the input stream are collected into a buffer until we have a chunk
385+-- of @reqSize@ and then written to the IO device.
362386--
363387-- @since 0.7.0
364−{-# INLINE writeInChunksOf #-}
365−writeInChunksOf :: MonadIO m => Int -> Handle -> Fold m Word8 ()
366−writeInChunksOf n h = FL.lchunksOf n (writeNUnsafe n) (writeArrays h)
388+{-# INLINE writeRequestsOf #-}
389+writeRequestsOf :: MonadIO m => Int -> Handle -> Fold m Word8 ()
390+writeRequestsOf n h = FL.lchunksOf n (writeNUnsafe n) (writeChunks h)
367391
368−-- > write = 'writeInChunksOf' A.defaultChunkSize
392+-- > write = 'writeRequestsOf' A.defaultChunkSize
369393--
370394-- | Write a byte stream to a file handle. Accumulates the input in chunks of
371−-- up to 'A.defaultChunkSize' before writing.
395+-- up to 'Streamly.Internal.Memory.Array.Types.defaultChunkSize' before writing
396+-- to the IO device.
372397--
373398-- @since 0.7.0
374399{-# INLINE write #-}
375400write :: MonadIO m => Handle -> Fold m Word8 ()
376−write = writeInChunksOf defaultChunkSize
401+write = writeRequestsOf defaultChunkSize
377402
378403{-
379404{-# INLINE write #-}