| Copyright | (c) 2018 Composewell Technologies |
|---|---|
| License | BSD3 |
| Maintainer | streamly@composewell.com |
| Stability | released |
| Portability | GHC |
| Safe Haskell | Safe-Inferred |
| Language | Haskell2010 |
Streamly.FileSystem.Handle
Description
>>>import qualified Streamly.FileSystem.Handle as Handle
Read and write byte streams and array streams to and from file handles
(Handle).
The TextEncoding, NewLineMode, and Buffering options of the underlying
GHC Handle are ignored by these APIs. Please use Streamly.Unicode.*
modules for encoding and decoding a byte stream, use stream splitting
operations in Streamly.Prelude to create a stream of lines or to split the
input stream on any other type of boundaries.
To set the read or write start position use hSeek on the Handle, the
before combinator may be used to do that on a streaming
combinator. To restrict the length of read or write use the stream trimming
operations like take.
Note that a Handle is inherently stateful, therefore, we cannot use these
APIs from multiple threads without serialization; reading or writing in one
thread would affect the file position for other threads.
For additional, experimental APIs take a look at Streamly.Internal.FileSystem.Handle module.
Synopsis
- getChunk :: MonadIO m => Int -> Handle -> m (Array Word8)
- putChunk :: (MonadIO m, Storable a) => Handle -> Array a -> m ()
- 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) ()
Singleton IO
Read or write a single buffer.
getChunk :: MonadIO m => Int -> Handle -> m (Array Word8) Source #
Read a ByteArray consisting of one or more bytes from a file handle. If
no data is available on the handle it blocks until at least one byte becomes
available. If any data is available then it immediately returns that data
without blocking. As a result of this behavior, it may read less than or
equal to the size requested.
Since: 0.8.1
putChunk :: (MonadIO m, Storable a) => Handle -> Array a -> m () Source #
Write an Array to a file handle.
Since: 0.8.1
Streaming IO
Read or write a stream of data to or from a file or device sequentially.
Read requests to the IO device are performed in chunks limited to a
maximum size of defaultChunkSize. Note
that the size of the actual chunks in the resulting stream may be less
than the defaultChunkSize but it can never exceed it. If the whole
stream is not consumed, it is possible that we may have 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.
Reading
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.
>>>read = Unfold.many Handle.readChunks Array.read
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.
>>>readWithBufferOf = Unfold.many Handle.readChunksWithBufferOf Array.read
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.
>>>readChunks = Unfold.supplyFirst IO.defaultChunkSize Handle.readChunksWithBufferOf
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
Writing
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.
>>>write = Handle.writeWithBufferOf IO.defaultChunkSize
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.
>>>writeWithBufferOf n h = Fold.chunksOf n (Array.writeNUnsafe n) (Handle.writeChunks h)
Since: 0.7.0