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.
Modulestreamly-core-0.2.2Haskell2010
Streamly.FileSystem.Handle
import qualified Streamly.FileSystem.Handle as HandleRead 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.Stream
module for encoding and decoding a byte stream, use stream splitting
operations in Streamly.Data.Stream 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
Streamly.Data.Stream.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 Streamly.Data.Stream.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.
- 17 values
- Packagestreamly-core-0.2.2
- Exports17
- LanguageHaskell2010
- LicenceBSD-3-Clause
- SourceHandle.hs
Setup
0 declarationsTo execute the code examples provided in this module in ghci, please run the following commands first.
:mimport qualified Streamly.Data.Array as Arrayimport qualified Streamly.FileSystem.Handle as Handle hiding (readChunks)import qualified Streamly.Data.Fold as Foldimport qualified Streamly.Data.Stream as Streamimport qualified Streamly.Data.Unfold as Unfold
For APIs that have not been released yet.
import qualified Streamly.Internal.Data.Array as Array (unsafeCreateOf)import qualified Streamly.Internal.Data.Unfold as Unfold (first)import qualified Streamly.Internal.FileSystem.Handle as Handleimport qualified Streamly.Internal.System.IO as IO (defaultChunkSize)
Singleton IO
2 declarationsRead or write a single buffer.
Write an Array to a file handle.
Streaming IO
0 declarationsRead 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.
Streams
Generate a byte stream from a file Handle.
read h = Stream.unfoldMany Array.reader $ Handle.readChunks hPre-release
readWith bufsize handle reads a byte stream from a file
handle, reads are performed in chunks of up to bufsize.
readWith size h = Stream.unfoldMany Array.reader $ Handle.readChunksWith size hPre-release
getChunks handle reads a stream of arrays from the specified file
handle. The maximum size of a single array is limited to
defaultChunkSize. The actual size read may be less than or equal to
defaultChunkSize.
readChunks = Handle.readChunksWith IO.defaultChunkSizePre-release
readChunksWith size handle reads a stream of arrays from the file
handle handle. The maximum size of a single array is limited to size.
The actual size read may be less than or equal to size.
readChunksWith size h = Stream.unfold Handle.chunkReaderWith (size, h)Unfolds
Unfolds a file handle into a byte stream. IO requests to the device are
performed in sizes of
Streamly.Internal.Data.Array.Type.defaultChunkSize.
reader = Unfold.many Array.reader Handle.chunkReaderUnfolds the tuple (bufsize, handle) into a byte stream, read requests
to the IO device are performed using buffers of bufsize.
readerWith = Unfold.many Array.reader Handle.chunkReaderWithUnfolds a handle into a stream of Word8 arrays. Requests to the IO
device are performed using a buffer of size
Streamly.Internal.Data.Array.Type.defaultChunkSize. The
size of arrays in the resulting stream are therefore less than or equal to
Streamly.Internal.Data.Array.Type.defaultChunkSize.
chunkReader = Unfold.first IO.defaultChunkSize Handle.chunkReaderWithUnfold 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.
Folds
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 a byte stream to a file handle. Accumulates the input in chunks of
up to Streamly.Internal.Data.Array.Type.defaultChunkSize before writing
to the IO device.
write = Handle.writeWith IO.defaultChunkSizewriteWith 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.
writeWith n h = Fold.groupsOf n (Array.unsafeCreateOf n) (Handle.writeChunks h)Write a stream of arrays to a handle. Each array in the stream is written to the device as a separate IO request.
writeChunks h = Fold.drainBy (Handle.putChunk h)
Deprecated
4 declarationsDeprecated. Please use readerWith instead.
Same as readerWith
Deprecated. Please use chunkReaderWith instead.
Same as chunkReaderWith
Deprecated. Please use writeChunksWith instead.
Same as writeChunksWith
Deprecated. Please use writeWith instead.
Same as writeWith