@@ -18,19 +18,22 @@
1818-- Read and write streams and arrays to and from file handles. File handle IO
1919-- APIs are quite similar to "Streamly.Mem.Array" read write APIs. In that
2020-- regard, arrays can be considered as in-memory files or files can be
21−-- considered as on-disk arrays. IO APIs are divided into two categories,
22−-- sequential streaming IO APIs and random access IO APIs. Control over the
23−-- file reading and writing behavior in terms of buffering, encoding, decoding
24−-- is in the hands of the programmer, the 'TextEncoding', 'NewLineMode', and
25−-- 'Buffering' options of the underlying handle provided by GHC are not needed
26−-- and ignored.
21+-- considered as on-disk arrays.
22+--
23+-- Control over file reading and writing behavior in terms of buffering,
24+-- encoding, decoding is in the hands of the programmer, the 'TextEncoding',
25+-- 'NewLineMode', and 'Buffering' options of the underlying handle provided by
26+-- GHC are not needed and ignored.
2727--
2828-- > import qualified Streamly.FileSystem.Handle as FH
2929--
3030
31+-- IO APIs are divided into two categories, sequential streaming IO APIs and
32+-- random access IO APIs.
33+
3134module Streamly.FileSystem.Handle
3235 (
33− -- * Streaming IO
36+ -- * Sequential/Streaming IO
3437 -- | Stream data to or from a file or device sequentially. When reading,
3538 -- the stream is lazy and generated on-demand as the consumer consumes it.
3639 -- Read IO requests to the IO device are performed in chunks limited to a
@@ -48,7 +51,12 @@ module Streamly.FileSystem.Handle
4851 -- Devices like terminals, pipes, sockets and fifos do not have random
4952 -- access capability.
5053
51− -- ** Read Handle to Stream
54+ -- ** Read From Handle
55+ -- | 'TextEncoding', 'NewLineMode', and 'Buffering' options of the
56+ -- underlying handle are ignored. The read occurs from the current seek
57+ -- position of the file handle. The stream ends as soon as EOF is
58+ -- encountered.
59+
5260 read
5361 -- , readUtf8
5462 -- , readLines
@@ -63,7 +71,12 @@ module Streamly.FileSystem.Handle
6371 -- , readArraysOf
6472 , readArrays
6573
66− -- ** Write File from Stream
74+ -- ** Write to Handle
75+ -- | 'TextEncoding', 'NewLineMode', and 'Buffering' options of the
76+ -- underlying handle are ignored. The write occurs from the current seek
77+ -- position of the file handle. The write behavior depends on the 'IOMode'
78+ -- of the handle.
79+ --
6780 , write
6881 -- , writeUtf8
6982 -- , writeUtf8ByLines
@@ -157,7 +170,7 @@ readArrayUpto size h = do
157170-- Array IO (output)
158171-------------------------------------------------------------------------------
159172
160−-- | Write an Array to a file handle.
173+-- | Write an 'Array' to a file handle.
161174--
162175-- @since 0.7.0
163176{-# INLINABLE writeArray #-}
@@ -188,6 +201,10 @@ _readArraysOfUpto size h = go
188201 then stp
189202 else yld arr go
190203
204+-- | @readArraysOfUpto size handle@ reads a stream of arrays from the file
205+-- handle @handle@. The maximum size of a single array is limited to @size@.
206+--
207+-- @since 0.7.0
191208{-# INLINE_NORMAL readArraysOfUpto #-}
192209readArraysOfUpto :: (IsStream t, MonadIO m) => Int -> Handle -> t m (Array Word8)
193210readArraysOfUpto size h = D.fromStreamD (D.Stream step ())
@@ -202,10 +219,9 @@ readArraysOfUpto size h = D.fromStreamD (D.Stream step ())
202219
203220-- XXX read 'Array a' instead of Word8
204221--
205−-- | @readArrays h@ reads a stream of arrays from file handle @h@.
206−-- The maximum size of a single array is limited to @defaultChunkSize@.
207−-- 'readArrays' ignores the prevailing 'TextEncoding' and 'NewlineMode'
208−-- on the 'Handle'.
222+-- | @readArrays handle@ reads a stream of arrays from the specified file
223+-- handle. The maximum size of a single array is limited to
224+-- @defaultChunkSize@.
209225--
210226-- > readArrays = readArraysOfUpto defaultChunkSize
211227--
@@ -223,19 +239,19 @@ readArrays = readArraysOfUpto defaultChunkSize
223239-- also control the read throughput in mbps or IOPS.
224240
225241-- | @readByChunksUpto chunkSize handle@ reads a byte stream from a file
226−-- handle, reads are performed in chunks of up to @chunkSize@. The stream ends
227−-- as soon as EOF is encountered.
242+-- handle, reads are performed in chunks of up to @chunkSize@.
228243--
244+-- @since 0.7.0
229245{-# INLINE readByChunksUpto #-}
230246readByChunksUpto :: (IsStream t, MonadIO m) => Int -> Handle -> t m Word8
231247readByChunksUpto chunkSize h = A.flattenArrays $ readArraysOfUpto chunkSize h
232248
233249-- TODO
250+-- Generate a stream of elements of the given type from a file 'Handle'.
234251-- read :: (IsStream t, MonadIO m, Storable a) => Handle -> t m a
235252--
236253-- > read = 'readByChunks' A.defaultChunkSize
237−-- | Generate a stream of elements of the given type from a file 'Handle'. The
238−-- stream ends when EOF is encountered.
254+-- | Generate a byte stream from a file 'Handle'.
239255--
240256-- @since 0.7.0
241257{-# INLINE read #-}
@@ -253,10 +269,10 @@ read = A.flattenArrays . readArrays
253269writeArrays :: (MonadIO m, Storable a) => Handle -> SerialT m (Array a) -> m ()
254270writeArrays h m = S.mapM_ (liftIO . writeArray h) m
255271
256−-- | Write a stream of arrays to a handle after coalescing them in chunks of
257−-- specified size. The chunk size is only a maximum and the actual writes could
258−-- be smaller than that as we do not split the arrays to fit them to the
259−-- specified size.
272+-- | @writeArraysPackedUpto chunkSize handle stream@ writes a stream of arrays
273+-- to @handle@ after coalescing the adjacent arrays in chunks of @chunkSize@.
274+-- The chunk size is only a maximum and the actual writes could be smaller as
275+-- we do not split the arrays to fit exactly to the specified size.
260276--
261277-- @since 0.7.0
262278{-# INLINE writeArraysPackedUpto #-}
@@ -272,9 +288,9 @@ writeArraysPackedUpto n h xs = writeArrays h $ A.packArraysChunksOf n xs
272288-- do not want buffering to occur at GHC level as well. Same thing applies to
273289-- writes as well.
274290
275−-- | Like 'write' but provides control over the write buffer. Output will
276−-- be written to the IO device as soon as we collect the specified number of
277−-- input elements.
291+-- | @writeByChunksOf chunkSize handle stream@ writes @stream@ to @handle@ in
292+-- chunks of @chunkSize@. A write is performed to the IO device as soon as we
293+-- collect the required input size.
278294--
279295-- @since 0.7.0
280296{-# INLINE writeByChunksOf #-}
@@ -283,9 +299,8 @@ writeByChunksOf n h m = writeArrays h $ A.arraysOf n m
283299
284300-- > write = 'writeByChunksOf' A.defaultChunkSize
285301--
286−-- | Write a byte stream to a file handle. Combines the bytes in chunks of size
287−-- up to 'A.defaultChunkSize' before writing. Note that the write behavior
288−-- depends on the 'IOMode' and the current seek position of the handle.
302+-- | Write a byte stream to a file handle. Combines the bytes in chunks of
303+-- up to 'A.defaultChunkSize' before writing.
289304--
290305-- @since 0.7.0
291306{-# INLINE write #-}
@@ -370,6 +385,23 @@ writeByFrames :: (IsStream t, MonadIO m, Storable a)
370385 => Array a -> Handle -> t m a -> m ()
371386writeByFrames = undefined
372387
388+-------------------------------------------------------------------------------
389+-- Framing by time
390+-------------------------------------------------------------------------------
391+
392+-- | Write collecting the input in sessions of n seconds or if chunkSize
393+-- gets exceeded.
394+{-# INLINE writeByChunksOrSessionsOf #-}
395+writeByChunksOrSessionsOf :: MonadIO m
396+ => Int -> Double -> Handle -> SerialT m Word8 -> m ()
397+writeByChunksOrSessionsOf chunkSize sessionSize h m = undefined
398+
399+-- | Write collecting the input in sessions of n seconds or if defaultChunkSize
400+-- gets exceeded.
401+{-# INLINE writeBySessionsOf #-}
402+writeBySessionsOf :: MonadIO m => Double -> Handle -> SerialT m Word8 -> m ()
403+writeBySessionsOf n = writeByChunksOrSessionsOf defaultChunkSize n
404+
373405-------------------------------------------------------------------------------
374406-- Random Access IO (Seek)
375407-------------------------------------------------------------------------------