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