streamly-0.8.0: Dataflow programming and declarative concurrency
Copyright(c) 2018 Composewell Technologies
LicenseBSD3
Maintainerstreamly@composewell.com
Stabilityreleased
PortabilityGHC
Safe HaskellNone
LanguageHaskell2010

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

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

writeWithBufferOf :: MonadIO m => Int -> Handle -> Fold m Word8 () Source #

writeWithBufferOf reqSize handle writes the input stream to handle. Bytes in the input stream are collected into a buffer until we have a chunk of reqSize and then written to the IO device.

Since: 0.7.0

writeChunks :: (MonadIO m, Storable a) => Handle -> Fold m (Array a) () Source #

Write a stream of arrays to a handle. Each array in the stream is written to the device as a separate IO request.

Since: 0.7.0