git.iko.soy/streamly
on master help sign in
streamly/core/src/Streamly/FileSystem/File.hs
60 lines 2.3 kB history raw
1-- |
2-- Module : Streamly.FileSystem.File
3-- Copyright : (c) 2019 Composewell Technologies
4--
5-- License : BSD3
6-- Maintainer : streamly@composewell.com
7-- Stability : pre-release
8-- Portability : GHC
9--
10-- Warning\: The API of this module is subject to change in future releases.
11-- Especially the type for representing paths may change from 'FilePath' to
12-- something else.
13--
14-- Read and write streams and arrays to and from files specified by their paths
15-- in the file system. Unlike the handle based APIs which can have a read/write
16-- session consisting of multiple reads and writes to the handle, these APIs
17-- are one shot read or write APIs. These APIs open the file handle, perform
18-- the requested operation and close the handle. These are safer compared to
19-- the handle based APIs as there is no possibility of a file descriptor
20-- leakage.
21--
22-- >>> import qualified Streamly.FileSystem.File as File
23--
24module Streamly.FileSystem.File
25 (
26 -- * Streaming IO
27 -- | Stream data to or from a file or device sequentially. When reading,
28 -- the stream is lazy and generated on-demand as the consumer consumes it.
29 -- Read IO requests to the IO device are performed in chunks limited to a
30 -- maximum size of 32KiB, this is referred to as @defaultChunkSize@ in the
31 -- documentation. One IO request may or may not read the full
32 -- chunk. If the whole stream is not consumed, it is possible that we may
33 -- read slightly more from the IO device than what the consumer needed.
34 -- Unless specified otherwise in the API, writes are collected into chunks
35 -- of @defaultChunkSize@ before they are written to the IO device.
37 -- Streaming APIs work for all kind of devices, seekable or non-seekable;
38 -- including disks, files, memory devices, terminals, pipes, sockets and
39 -- fifos. While random access APIs work only for files or devices that have
40 -- random access or seek capability for example disks, memory devices.
41 -- Devices like terminals, pipes, sockets and fifos do not have random
42 -- access capability.
44 -- ** File IO Using Handle
45 withFile
47 -- ** Streams
48 , read
49 , readChunksWith
50 , readChunks
52 -- ** Folds
53 , write
54 , writeWith
55 , writeChunks
56 )
57where
59import Streamly.Internal.FileSystem.File
60import Prelude hiding (read)