| Copyright | (c) 2018 Composewell Technologies |
|---|---|
| License | BSD3 |
| Maintainer | streamly@composewell.com |
| Stability | released |
| Portability | GHC |
| Safe Haskell | None |
| Language | Haskell2010 |
Streamly.FileSystem.Handle
Description
Read and write streams and arrays to and from file handles. File handle IO APIs are quite similar to Streamly.Data.Array.Foreign read write APIs. In that regard, arrays can be considered as in-memory files or files can be considered as on-disk arrays.
Control over file reading and writing behavior in terms of buffering,
encoding, decoding is in the hands of the programmer, the TextEncoding,
NewLineMode, and Buffering options of the underlying handle provided by
GHC are not needed and ignored.
Programmer Notes
import qualified Streamly.FileSystem.Handle as Handle
For additional, experimental APIs take a look at Streamly.Internal.FileSystem.Handle module.
Performance Notes
In some cases the stream type based APIs in the Streamly.Internal.FileSystem.Handle module may be more efficient compared to the unfold/fold based APIs exposed from this module because of better fusion by GHC. However, with the streamly fusion GHC plugin (upcoming) these APIs would perform as well as the stream based APIs in all cases.
Synopsis
- read :: MonadIO m => Unfold m Handle Word8
- readWithBufferOf :: MonadIO m => Unfold m (Int, Handle) Word8
- readChunks :: MonadIO m => Unfold m Handle (Array Word8)
- readChunksWithBufferOf :: MonadIO m => Unfold m (Int, Handle) (Array Word8)
- write :: MonadIO m => Handle -> Fold m Word8 ()
- writeWithBufferOf :: MonadIO m => Int -> Handle -> Fold m Word8 ()
- writeChunks :: (MonadIO m, Storable a) => Handle -> Fold m (Array a) ()
Sequential/Streaming IO
Stream data to or from a file or device sequentially. When reading,
the stream is lazy and generated on-demand as the consumer consumes it.
Read IO requests to the IO device are performed in chunks limited to a
maximum size of 32KiB, this is referred to as
defaultChunkSize in the
documentation. One IO request may or may not read the full
chunk. If the whole stream is not consumed, it is possible that we may
read slightly more from the IO device than what the consumer needed.
Unless specified otherwise in the API, writes are collected into chunks
of defaultChunkSize before they
are written to the IO device.
Read From Handle
TextEncoding, NewLineMode, and Buffering options of the
underlying handle are ignored. The read occurs from the current seek
position of the file handle. The stream ends as soon as EOF is
encountered.
read :: MonadIO m => Unfold m Handle Word8 Source #
Unfolds a file handle into a byte stream. IO requests to the device are
performed in sizes of
defaultChunkSize.
Since: 0.7.0
readWithBufferOf :: MonadIO m => Unfold m (Int, Handle) Word8 Source #
Unfolds the tuple (bufsize, handle) into a byte stream, read requests
to the IO device are performed using buffers of bufsize.
Since: 0.7.0
readChunks :: MonadIO m => Unfold m Handle (Array Word8) Source #
Unfolds a handle into a stream of Word8 arrays. Requests to the IO
device are performed using a buffer of size
defaultChunkSize. The
size of arrays in the resulting stream are therefore less than or equal to
defaultChunkSize.
Since: 0.7.0
readChunksWithBufferOf :: MonadIO m => Unfold m (Int, Handle) (Array Word8) Source #
Unfold the tuple (bufsize, handle) into a stream of Word8 arrays.
Read requests to the IO device are performed using a buffer of size
bufsize. The size of an array in the resulting stream is always less than
or equal to bufsize.
Since: 0.7.0
Write to Handle
TextEncoding, NewLineMode, and Buffering options of the
underlying handle are ignored. The write occurs from the current seek
position of the file handle. The write behavior depends on the IOMode
of the handle.
write :: MonadIO m => Handle -> Fold m Word8 () Source #
Write a byte stream to a file handle. Accumulates the input in chunks of
up to defaultChunkSize before writing
to the IO device.
Since: 0.7.0