| Copyright | (c) 2019 Composewell Technologies |
|---|---|
| License | BSD3 |
| Maintainer | streamly@composewell.com |
| Stability | pre-release |
| Portability | GHC |
| Safe Haskell | None |
| Language | Haskell2010 |
Streamly.FileSystem.FileIO
Description
Read and write streams and arrays to and from files specified by their paths in the file system. These APIs open the file handle, perform the requested operation and close the handle. These are higher level and safer compared to the handle based APIs as there is no possibility of a file descriptor leakage.
Files are always opened in:
- Binary mode — encoding, decoding, and newline translation should be handled explicitly by the streaming APIs.
- Unbuffered mode — buffering can be managed explicitly via streaming APIs.
File system paths are specified using the Path
type. If you want to convert between String or FilePath and Path use
fromString_, toString
from the Streamly.FileSystem.Path module..
> import qualified Streamly.FileSystem.FileIO as File
Synopsis
- withFile :: forall (m :: Type -> Type) a. (MonadIO m, MonadCatch m) => Path -> IOMode -> (Handle -> Stream m a) -> Stream m a
- read :: forall (m :: Type -> Type). (MonadIO m, MonadCatch m) => Path -> Stream m Word8
- readChunksWith :: forall (m :: Type -> Type). (MonadIO m, MonadCatch m) => Int -> Path -> Stream m (Array Word8)
- readChunks :: forall (m :: Type -> Type). (MonadIO m, MonadCatch m) => Path -> Stream m (Array Word8)
- write :: forall (m :: Type -> Type). (MonadIO m, MonadCatch m) => Path -> Fold m Word8 ()
- writeWith :: forall (m :: Type -> Type). (MonadIO m, MonadCatch m) => Int -> Path -> Fold m Word8 ()
- writeChunks :: forall (m :: Type -> Type) a. (MonadIO m, MonadCatch m) => Path -> Fold m (Array a) ()
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.
When writing, unless specified otherwise in the API, writes are
collected into chunks of defaultChunkSize before they are written to
the IO device.
File IO Using Handle
withFile :: forall (m :: Type -> Type) a. (MonadIO m, MonadCatch m) => Path -> IOMode -> (Handle -> Stream m a) -> Stream m a Source #
withFile name mode actact. The handle is closed on exit from withFile, whether
by normal termination or by raising an exception. If closing the handle
raises an exception, then that exception is raised by withFile rather than
any exception raised by act.
The file is opened in binary mode as encoding, decoding, and newline translation can be handled explicitly by the streaming APIs.
The file is opened without buffering as buffering can be controlled explicitly by the streaming APIs.
Pre-release
Streams
read :: forall (m :: Type -> Type). (MonadIO m, MonadCatch m) => Path -> Stream m Word8 Source #
Generate a stream of bytes from a file specified by path. The stream ends when EOF is encountered. File is locked using multiple reader and single writer locking mode.
Pre-release
readChunksWith :: forall (m :: Type -> Type). (MonadIO m, MonadCatch m) => Int -> Path -> Stream m (Array Word8) Source #
readChunksWith size file reads a stream of arrays from file file.
The maximum size of a single array is specified by size. The actual size
read may be less than or equal to size.
Pre-release
readChunks :: forall (m :: Type -> Type). (MonadIO m, MonadCatch m) => Path -> Stream m (Array Word8) Source #
readChunks file reads a stream of arrays from file file.
The maximum size of a single array is limited to defaultChunkSize. The
actual size read may be less than defaultChunkSize.
readChunks = readChunksWith defaultChunkSize
Pre-release
Folds
write :: forall (m :: Type -> Type). (MonadIO m, MonadCatch m) => Path -> Fold m Word8 () Source #
Write a byte stream to a file. Accumulates the input in chunks of up to
defaultChunkSize before writing to
the IO device.
Pre-release
writeWith :: forall (m :: Type -> Type). (MonadIO m, MonadCatch m) => Int -> Path -> Fold m Word8 () Source #
writeWith chunkSize handle writes the input stream to handle.
Bytes in the input stream are collected into a buffer until we have a chunk
of size chunkSize and then written to the IO device.
Pre-release
writeChunks :: forall (m :: Type -> Type) a. (MonadIO m, MonadCatch m) => Path -> Fold m (Array a) () Source #
Write a stream of chunks to a file. Each chunk in the stream is written immediately to the device as a separate IO request, without coalescing or buffering.