@@ -11,13 +11,13 @@
1111--
1212-- The fundamental singleton IO APIs are 'getChunk' and 'putChunk' and the
1313-- fundamental stream IO APIs built on top of those are
14−-- 'readChunksWithBufferOf' and 'writeChunks'. Rest of this module is just
14+-- 'readChunksWith' and 'writeChunks'. Rest of this module is just
1515-- combinatorial programming using these.
1616--
1717-- We can achieve line buffering by folding lines in the input stream into a
1818-- stream of arrays using Stream.splitOn or Fold.takeEndBy_ and similar
1919-- operations. One can wrap the input stream in 'Maybe' type and then use
20−-- 'writeMaybesWithBufferOf' to achieve user controlled buffering.
20+-- 'writeMaybesWith' to achieve user controlled buffering.
2121
2222-- TODO: Need a separate module for pread/pwrite based reading writing for
2323-- seekable devices. Stateless read/write can be helpful in multithreaded
@@ -35,17 +35,17 @@ module Streamly.Internal.FileSystem.Handle
3535 -- , readUtf8
3636 -- , readLines
3737 -- , readFrames
38− , readWithBufferOf
38+ , readWith
3939
40− , toBytes
41− , toBytesWithBufferOf
40+ , getBytes
41+ , getBytesWith
4242
4343 -- * Chunked Stream Read
4444 , readChunks
45− , readChunksWithBufferOf
45+ , readChunksWith
4646
47− , toChunksWithBufferOf
48− , toChunks
47+ , getChunksWith
48+ , getChunks
4949
5050 -- * Byte Stream Write
5151 -- Byte stream write (Folds)
@@ -55,17 +55,17 @@ module Streamly.Internal.FileSystem.Handle
5555 -- , writeUtf8ByLines
5656 -- , writeByFrames
5757 -- , writeLines
58− , writeWithBufferOf
59− , writeMaybesWithBufferOf
58+ , writeWith
59+ , writeMaybesWith
6060
6161 , putBytes
62− , putBytesWithBufferOf
62+ , putBytesWith
6363
6464 -- * Chunked Stream Write
6565 , writeChunks
66− , writeChunksWithBufferOf
66+ , writeChunksWith
6767
68− , putChunksWithBufferOf
68+ , putChunksWith
6969 , putChunks
7070
7171 -- * Random Access (Seek)
@@ -101,6 +101,11 @@ module Streamly.Internal.FileSystem.Handle
101101 -- , writeChunksFromTo
102102 -- , writeChunksFromToWith
103103 -- , writeChunksFromThenToWith
104+ -- * Deprecated
105+ , readChunksWithBufferOf
106+ , readWithBufferOf
107+ , writeChunksWithBufferOf
108+ , writeWithBufferOf
104109 )
105110where
106111
@@ -203,13 +208,14 @@ getChunkOf = undefined
203208-- Stream of Arrays IO
204209-------------------------------------------------------------------------------
205210
206−-- | @toChunksWithBufferOf size h@ reads a stream of arrays from file handle @h@.
211+-- | @getChunksWith size h@ reads a stream of arrays from file handle @h@.
207212-- The maximum size of a single array is specified by @size@. The actual size
208213-- read may be less than or equal to @size@.
209−{-# INLINE _toChunksWithBufferOf #-}
210−_toChunksWithBufferOf :: (IsStream t, MonadIO m)
214+-- @since 0.9.0
215+{-# INLINE _getChunksWith #-}
216+_getChunksWith :: (IsStream t, MonadIO m)
211217 => Int -> Handle -> t m (Array Word8)
212−_toChunksWithBufferOf size h = go
218+_getChunksWith size h = go
213219 where
214220 -- XXX use cons/nil instead
215221 go = mkStream $ \_ yld _ stp -> do
@@ -218,22 +224,17 @@ _toChunksWithBufferOf size h = go
218224 then stp
219225 else yld arr go
220226
221−-- | @toChunksWithBufferOf size handle@ reads a stream of arrays from the file
227+-- | @getChunksWith size handle@ reads a stream of arrays from the file
222228-- handle @handle@. The maximum size of a single array is limited to @size@.
223229-- The actual size read may be less than or equal to @size@.
224230--
225−-- >>> toChunksWithBufferOf size h = Stream.unfold Handle.readChunksWithBufferOf (size, h)
231+-- >>> getChunksWith size h = Stream.unfold Handle.readChunksWith (size, h)
226232--
227−-- @since 0.7.0
228−{-# INLINE_NORMAL toChunksWithBufferOf #-}
229−toChunksWithBufferOf :: (IsStream t, MonadIO m) =>
233+-- @since 0.9.0
234+{-# INLINE_NORMAL getChunksWith #-}
235+getChunksWith :: (IsStream t, MonadIO m) =>
230236 Int -> Handle -> t m (Array Word8)
231−{-
232−toChunksWithBufferOf size h =
233− S.repeatM (getChunk size h)
234− & S.takeWhile ((/= 0) . byteLength)
235−-}
236−toChunksWithBufferOf size h = fromStreamD (D.Stream step ())
237+getChunksWith size h = fromStreamD (D.Stream step ())
237238 where
238239 {-# INLINE_LATE step #-}
239240 step _ _ = do
@@ -248,31 +249,27 @@ toChunksWithBufferOf size h = fromStreamD (D.Stream step ())
248249-- @bufsize@. The size of an array in the resulting stream is always less than
249250-- or equal to @bufsize@.
250251--
251−-- @since 0.7.0
252−{-# INLINE_NORMAL readChunksWithBufferOf #-}
253−readChunksWithBufferOf :: MonadIO m => Unfold m (Int, Handle) (Array Word8)
254−readChunksWithBufferOf =
252+-- @since 0.9.0
253+{-# INLINE_NORMAL readChunksWith #-}
254+readChunksWith :: MonadIO m => Unfold m (Int, Handle) (Array Word8)
255+readChunksWith =
255256 UF.lmap (uncurry getChunk) UF.repeatM
256257 & UF.takeWhile ((/= 0) . byteLength)
257−{-
258−readChunksWithBufferOf = Unfold step return
259258
260− where
261259
262− {-# INLINE_LATE step #-}
263− step (size, h) = do
264− arr <- getChunk size h
265− return $
266− case byteLength arr of
267− 0 -> D.Stop
268− _ -> D.Yield arr (size, h)
269−-}
260+-- | Same as 'readChunksWith'
261+--
262+-- @since 0.7.0
263+{-# DEPRECATED readChunksWithBufferOf "Please use readChunksWith instead." #-}
264+{-# INLINE_NORMAL readChunksWithBufferOf #-}
265+readChunksWithBufferOf :: MonadIO m => Unfold m (Int, Handle) (Array Word8)
266+readChunksWithBufferOf = readChunksWith
270267
271268-- There are two ways to implement this.
272269--
273−-- 1. Idiomatic: use a scan on the output of readChunksWithBufferOf to total
270+-- 1. Idiomatic: use a scan on the output of readChunksWith to total
274271-- the array lengths and trim the last array to correct size.
275−-- 2. Simply implement it from scratch like readChunksWithBufferOf.
272+-- 2. Simply implement it from scratch like readChunksWith.
276273--
277274-- XXX Change this to readChunksWithFromTo (bufferSize, from, to, h)?
278275--
@@ -305,19 +302,20 @@ readChunksFromToWith = Unfold step inject
305302 assert (len <= remaining)
306303 $ D.Yield arr (remaining - len, bufSize, h)
307304
305+
308306-- XXX read 'Array a' instead of Word8
309307--
310−-- | @toChunks handle@ reads a stream of arrays from the specified file
308+-- | @getChunks handle@ reads a stream of arrays from the specified file
311309-- handle. The maximum size of a single array is limited to
312310-- @defaultChunkSize@. The actual size read may be less than or equal to
313311-- @defaultChunkSize@.
314312--
315−-- >>> toChunks = Handle.toChunksWithBufferOf IO.defaultChunkSize
313+-- >>> getChunks = Handle.getChunksWith IO.defaultChunkSize
316314--
317−-- @since 0.7.0
318−{-# INLINE toChunks #-}
319−toChunks :: (IsStream t, MonadIO m) => Handle -> t m (Array Word8)
320−toChunks = toChunksWithBufferOf defaultChunkSize
315+-- @since 0.9.0
316+{-# INLINE getChunks #-}
317+getChunks :: (IsStream t, MonadIO m) => Handle -> t m (Array Word8)
318+getChunks = getChunksWith defaultChunkSize
321319
322320-- | Unfolds a handle into a stream of 'Word8' arrays. Requests to the IO
323321-- device are performed using a buffer of size
@@ -325,12 +323,12 @@ toChunks = toChunksWithBufferOf defaultChunkSize
325323-- size of arrays in the resulting stream are therefore less than or equal to
326324-- 'Streamly.Internal.Data.Array.Foreign.Type.defaultChunkSize'.
327325--
328−-- >>> readChunks = Unfold.supplyFirst IO.defaultChunkSize Handle.readChunksWithBufferOf
326+-- >>> readChunks = Unfold.supplyFirst IO.defaultChunkSize Handle.readChunksWith
329327--
330328-- @since 0.7.0
331329{-# INLINE readChunks #-}
332330readChunks :: MonadIO m => Unfold m Handle (Array Word8)
333−readChunks = UF.supplyFirst defaultChunkSize readChunksWithBufferOf
331+readChunks = UF.supplyFirst defaultChunkSize readChunksWith
334332
335333-------------------------------------------------------------------------------
336334-- Read File to Stream
@@ -343,22 +341,30 @@ readChunks = UF.supplyFirst defaultChunkSize readChunksWithBufferOf
343341-- | Unfolds the tuple @(bufsize, handle)@ into a byte stream, read requests
344342-- to the IO device are performed using buffers of @bufsize@.
345343--
346−-- >>> readWithBufferOf = Unfold.many Array.read Handle.readChunksWithBufferOf
344+-- >>> readWith = Unfold.many Array.read Handle.readChunksWith
345+--
346+-- @since 0.9.0
347+{-# INLINE readWith #-}
348+readWith :: MonadIO m => Unfold m (Int, Handle) Word8
349+readWith = UF.many A.read readChunksWith
350+
351+-- | Same as 'readWith'
347352--
348353-- @since 0.7.0
354+{-# DEPRECATED readWithBufferOf "Please use readWith instead." #-}
349355{-# INLINE readWithBufferOf #-}
350356readWithBufferOf :: MonadIO m => Unfold m (Int, Handle) Word8
351−readWithBufferOf = UF.many A.read readChunksWithBufferOf
357+readWithBufferOf = readWith
352358
353−-- | @toBytesWithBufferOf bufsize handle@ reads a byte stream from a file
359+-- | @getBytesWith bufsize handle@ reads a byte stream from a file
354360-- handle, reads are performed in chunks of up to @bufsize@.
355361--
356−-- >>> toBytesWithBufferOf size h = Stream.unfoldMany Array.read $ Handle.toChunksWithBufferOf size h
362+-- >>> getBytesWith size h = Stream.unfoldMany Array.read $ Handle.getChunksWith size h
357363--
358364-- /Pre-release/
359−{-# INLINE toBytesWithBufferOf #-}
360−toBytesWithBufferOf :: (IsStream t, MonadIO m) => Int -> Handle -> t m Word8
361−toBytesWithBufferOf size h = AS.concat $ toChunksWithBufferOf size h
365+{-# INLINE getBytesWith #-}
366+getBytesWith :: (IsStream t, MonadIO m) => Int -> Handle -> t m Word8
367+getBytesWith size h = AS.concat $ getChunksWith size h
362368
363369-- TODO
364370-- Generate a stream of elements of the given type from a file 'Handle'.
@@ -377,12 +383,12 @@ read = UF.many A.read readChunks
377383
378384-- | Generate a byte stream from a file 'Handle'.
379385--
380−-- >>> toBytes h = Stream.unfoldMany Array.read $ Handle.toChunks h
386+-- >>> getBytes h = Stream.unfoldMany Array.read $ Handle.getChunks h
381387--
382388-- /Pre-release/
383−{-# INLINE toBytes #-}
384−toBytes :: (IsStream t, MonadIO m) => Handle -> t m Word8
385−toBytes = AS.concat . toChunks
389+{-# INLINE getBytes #-}
390+getBytes :: (IsStream t, MonadIO m) => Handle -> t m Word8
391+getBytes = AS.concat . getChunks
386392
387393-------------------------------------------------------------------------------
388394-- Writing
@@ -427,28 +433,29 @@ putChunks h = S.mapM_ (putChunk h)
427433-- AS.concat is written in terms of foldMany. Once that is done we can write
428434-- idiomatic def in the docs.
429435--
430−-- | @putChunksWithBufferOf bufsize handle stream@ writes a stream of arrays
436+-- | @putChunksWith bufsize handle stream@ writes a stream of arrays
431437-- to @handle@ after coalescing the adjacent arrays in chunks of @bufsize@.
432438-- The chunk size is only a maximum and the actual writes could be smaller as
433439-- we do not split the arrays to fit exactly to the specified size.
434440--
435−-- @since 0.7.0
436−{-# INLINE putChunksWithBufferOf #-}
437−putChunksWithBufferOf :: (MonadIO m, Storable a)
441+-- @since 0.9.0
442+{-# INLINE putChunksWith #-}
443+putChunksWith :: (MonadIO m, Storable a)
438444 => Int -> Handle -> SerialT m (Array a) -> m ()
439−putChunksWithBufferOf n h xs = putChunks h $ AS.compact n xs
445+putChunksWith n h xs = putChunks h $ AS.compact n xs
440446
441−-- | @putBytesWithBufferOf bufsize handle stream@ writes @stream@ to @handle@
447+-- | @putBytesWith bufsize handle stream@ writes @stream@ to @handle@
442448-- in chunks of @bufsize@. A write is performed to the IO device as soon as we
443449-- collect the required input size.
444450--
445−-- >>> putBytesWithBufferOf n h m = Handle.putChunks h $ Stream.arraysOf n m
451+-- >>> putBytesWith n h m = Handle.putChunks h $ Stream.arraysOf n m
446452--
447−-- @since 0.7.0
448−{-# INLINE putBytesWithBufferOf #-}
449−putBytesWithBufferOf :: MonadIO m => Int -> Handle -> SerialT m Word8 -> m ()
450−putBytesWithBufferOf n h m = putChunks h $ S.arraysOf n m
451−-- putBytesWithBufferOf n h m = putChunks h $ AS.arraysOf n m
453+-- @since 0.9.0
454+{-# INLINE putBytesWith #-}
455+putBytesWith :: MonadIO m => Int -> Handle -> SerialT m Word8 -> m ()
456+putBytesWith n h m = putChunks h $ S.arraysOf n m
457+
458+-- putBytesWith n h m = putChunks h $ AS.arraysOf n m
452459
453460-- | Write a byte stream to a file handle. Accumulates the input in chunks of
454461-- up to 'Streamly.Internal.Data.Array.Foreign.Type.defaultChunkSize' before writing.
@@ -456,12 +463,12 @@ putBytesWithBufferOf n h m = putChunks h $ S.arraysOf n m
456463-- NOTE: This may perform better than the 'write' fold, you can try this if you
457464-- need some extra perf boost.
458465--
459−-- >>> putBytes = Handle.putBytesWithBufferOf IO.defaultChunkSize
466+-- >>> putBytes = Handle.putBytesWith IO.defaultChunkSize
460467--
461468-- @since 0.7.0
462469{-# INLINE putBytes #-}
463470putBytes :: MonadIO m => Handle -> SerialT m Word8 -> m ()
464−putBytes = putBytesWithBufferOf defaultChunkSize
471+putBytes = putBytesWith defaultChunkSize
465472
466473-- | Write a stream of arrays to a handle. Each array in the stream is written
467474-- to the device as a separate IO request.
@@ -482,17 +489,26 @@ consumeChunks = Refold.drainBy putChunk
482489
483490-- XXX lpackArraysChunksOf should be written idiomatically
484491--
485−-- | @writeChunksWithBufferOf bufsize handle@ writes a stream of arrays
492+-- | @writeChunksWith bufsize handle@ writes a stream of arrays
486493-- to @handle@ after coalescing the adjacent arrays in chunks of @bufsize@.
487494-- We never split an array, if a single array is bigger than the specified size
488495-- it emitted as it is. Multiple arrays are coalesed as long as the total size
489496-- remains below the specified size.
490497--
498+-- @since 0.9.0
499+{-# INLINE writeChunksWith #-}
500+writeChunksWith :: (MonadIO m, Storable a)
501+ => Int -> Handle -> Fold m (Array a) ()
502+writeChunksWith n h = lpackArraysChunksOf n (writeChunks h)
503+
504+-- | Same as 'writeChunksWith'
505+--
491506-- @since 0.7.0
507+{-# DEPRECATED writeChunksWithBufferOf "Please use writeChunksWith instead." #-}
492508{-# INLINE writeChunksWithBufferOf #-}
493509writeChunksWithBufferOf :: (MonadIO m, Storable a)
494510 => Int -> Handle -> Fold m (Array a) ()
495−writeChunksWithBufferOf n h = lpackArraysChunksOf n (writeChunks h)
511+writeChunksWithBufferOf = writeChunksWith
496512
497513-- GHC buffer size dEFAULT_FD_BUFFER_SIZE=8192 bytes.
498514--
@@ -504,55 +520,63 @@ writeChunksWithBufferOf n h = lpackArraysChunksOf n (writeChunks h)
504520
505521-- XXX Maybe we should have a Fold.arraysOf like we have Stream.arraysOf
506522--
507−-- | @writeWithBufferOf reqSize handle@ writes the input stream to @handle@.
523+-- | @writeWith reqSize handle@ writes the input stream to @handle@.
508524-- Bytes in the input stream are collected into a buffer until we have a chunk
509525-- of @reqSize@ and then written to the IO device.
510526--
511−-- >>> writeWithBufferOf n h = Fold.chunksOf n (Array.writeNUnsafe n) (Handle.writeChunks h)
527+-- >>> writeWith n h = Fold.chunksOf n (Array.writeNUnsafe n) (Handle.writeChunks h)
528+--
529+-- @since 0.7.0
530+{-# INLINE writeWith #-}
531+writeWith :: MonadIO m => Int -> Handle -> Fold m Word8 ()
532+writeWith n h = FL.chunksOf n (writeNUnsafe n) (writeChunks h)
533+
534+-- | Same as 'writeWith'
512535--
513536-- @since 0.7.0
537+{-# DEPRECATED writeWithBufferOf "Please use writeWith instead." #-}
514538{-# INLINE writeWithBufferOf #-}
515539writeWithBufferOf :: MonadIO m => Int -> Handle -> Fold m Word8 ()
516−writeWithBufferOf n h = FL.chunksOf n (writeNUnsafe n) (writeChunks h)
540+writeWithBufferOf = writeWith
517541
518542-- | Write a stream of 'Maybe' values. Keep buffering the just values in an
519543-- array until a 'Nothing' is encountered or the buffer size exceeds the
520544-- specified limit, at that point flush the buffer to the handle.
521545--
522546-- /Pre-release/
523−{-# INLINE writeMaybesWithBufferOf #-}
524−writeMaybesWithBufferOf :: (MonadIO m )
547+{-# INLINE writeMaybesWith #-}
548+writeMaybesWith :: (MonadIO m )
525549 => Int -> Handle -> Fold m (Maybe Word8) ()
526−writeMaybesWithBufferOf n h =
550+writeMaybesWith n h =
527551 let writeNJusts = FL.lmap fromJust $ A.writeN n
528552 writeOnNothing = FL.takeEndBy_ isNothing writeNJusts
529553 in FL.many writeOnNothing (writeChunks h)
530554
531−-- | Like 'writeWithBufferOf' but uses the experimental 'Refold' API.
555+-- | Like 'writeWith' but uses the experimental 'Refold' API.
532556--
533557-- /Internal/
534−{-# INLINE consumerWithBufferOf #-}
535−consumerWithBufferOf :: MonadIO m => Int -> Refold m Handle Word8 ()
536−consumerWithBufferOf n =
558+{-# INLINE consumerWith #-}
559+consumerWith :: MonadIO m => Int -> Refold m Handle Word8 ()
560+consumerWith n =
537561 FL.refoldMany (FL.take n $ writeNUnsafe n) consumeChunks
538562
539563-- | Write a byte stream to a file handle. Accumulates the input in chunks of
540564-- up to 'Streamly.Internal.Data.Array.Foreign.Type.defaultChunkSize' before writing
541565-- to the IO device.
542566--
543−-- >>> write = Handle.writeWithBufferOf IO.defaultChunkSize
567+-- >>> write = Handle.writeWith IO.defaultChunkSize
544568--
545569-- @since 0.7.0
546570{-# INLINE write #-}
547571write :: MonadIO m => Handle -> Fold m Word8 ()
548−write = writeWithBufferOf defaultChunkSize
572+write = writeWith defaultChunkSize
549573
550574-- | Like 'write' but uses the experimental 'Refold' API.
551575--
552576-- /Internal/
553577{-# INLINE consumer #-}
554578consumer :: MonadIO m => Refold m Handle Word8 ()
555−consumer = consumerWithBufferOf defaultChunkSize
579+consumer = consumerWith defaultChunkSize
556580
557581{-
558582{-# INLINE write #-}