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