git.iko.soy/streamly
on f1c19a6 help sign in
streamly/src/Streamly/FileSystem/Handle.hs
86 lines 3.5 kB history raw
1#include "inline.hs"
3-- |
4-- Module : Streamly.FileSystem.Handle
5-- Copyright : (c) 2018 Composewell Technologies
6--
7-- License : BSD3
8-- Maintainer : streamly@composewell.com
9-- Stability : experimental
10-- Portability : GHC
11--
12-- Read and write streams and arrays to and from file handles. File handle IO
13-- APIs are quite similar to "Streamly.Data.Array.Foreign" read write APIs. In that
14-- regard, arrays can be considered as in-memory files or files can be
15-- considered as on-disk arrays.
16--
17-- Control over file reading and writing behavior in terms of buffering,
18-- encoding, decoding is in the hands of the programmer, the 'TextEncoding',
19-- 'NewLineMode', and 'Buffering' options of the underlying handle provided by
20-- GHC are not needed and ignored.
21--
22-- = Programmer Notes
23--
24-- > import qualified Streamly.FileSystem.Handle as FH
25--
26-- For additional, experimental APIs take a look at
27-- "Streamly.Internal.FileSystem.Handle" module.
28--
29-- = Performance Notes
30--
31-- In some cases the stream type based APIs in the
32-- "Streamly.Internal.FileSystem.Handle" module may be more efficient compared
33-- to the unfold/fold based APIs exposed from this module because of better
34-- fusion by GHC. However, with the streamly fusion GHC plugin (upcoming) these
35-- APIs would perform as well as the stream based APIs in all cases.
37-- IO APIs are divided into two categories, sequential streaming IO APIs and
38-- random access IO APIs.
40module Streamly.FileSystem.Handle
41 (
42 -- * Sequential/Streaming IO
43 -- | Stream data to or from a file or device sequentially. When reading,
44 -- the stream is lazy and generated on-demand as the consumer consumes it.
45 -- Read IO requests to the IO device are performed in chunks limited to a
46 -- maximum size of 32KiB, this is referred to as
47 -- 'Streamly.Internal.Data.Array.Foreign.Type.defaultChunkSize' in the
48 -- documentation. One IO request may or may not read the full
49 -- chunk. If the whole stream is not consumed, it is possible that we may
50 -- read slightly more from the IO device than what the consumer needed.
51 -- Unless specified otherwise in the API, writes are collected into chunks
52 -- of 'Streamly.Internal.Data.Array.Foreign.Type.defaultChunkSize' before they
53 -- are written to the IO device.
55 -- Streaming APIs work for all kind of devices, seekable or non-seekable;
56 -- including disks, files, memory devices, terminals, pipes, sockets and
57 -- fifos. While random access APIs work only for files or devices that have
58 -- random access or seek capability for example disks, memory devices.
59 -- Devices like terminals, pipes, sockets and fifos do not have random
60 -- access capability.
62 -- ** Read From Handle
63 -- | 'TextEncoding', 'NewLineMode', and 'Buffering' options of the
64 -- underlying handle are ignored. The read occurs from the current seek
65 -- position of the file handle. The stream ends as soon as EOF is
66 -- encountered.
68 read
69 , readWithBufferOf
70 , readChunks
71 , readChunksWithBufferOf
73 -- ** Write to Handle
74 -- | 'TextEncoding', 'NewLineMode', and 'Buffering' options of the
75 -- underlying handle are ignored. The write occurs from the current seek
76 -- position of the file handle. The write behavior depends on the 'IOMode'
77 -- of the handle.
79 , write
80 , writeWithBufferOf
81 , writeChunks
82 )
83where
85import Streamly.Internal.FileSystem.Handle
86import Prelude hiding (read)