git.iko.soy/streamly
on 2e53b60 help sign in
streamly/core/src/Streamly/FileSystem/Handle.hs
140 lines 4.7 kB history raw
1{-# LANGUAGE CPP #-}
2#include "inline.hs"
4-- |
5-- Module : Streamly.FileSystem.Handle
6-- Copyright : (c) 2018 Composewell Technologies
7--
8-- License : BSD3
9-- Maintainer : streamly@composewell.com
10-- Stability : released
11-- Portability : GHC
12--
13-- >>> import qualified Streamly.FileSystem.Handle as Handle
14--
15-- Read and write byte streams and array streams to and from file handles
16-- ('Handle').
17--
18-- The 'TextEncoding', 'NewLineMode', and 'Buffering' options of the underlying
19-- GHC 'Handle' are ignored by these APIs. Please use "Streamly.Unicode.Stream"
20-- module for encoding and decoding a byte stream, use stream splitting
21-- operations in "Streamly.Data.Stream" to create a stream of lines or to split
22-- the input stream on any other type of boundaries.
23--
24-- To set the read or write start position use 'hSeek' on the 'Handle', the
25-- 'Streamly.Data.Stream.before' combinator may be used to do that on a
26-- streaming combinator. To restrict the length of read or write use the stream
27-- trimming operations like 'Streamly.Data.Stream.take'.
28--
29-- Note that a 'Handle' is inherently stateful, therefore, we cannot use these
30-- APIs from multiple threads without serialization; reading or writing in one
31-- thread would affect the file position for other threads.
32--
33-- For additional, experimental APIs take a look at
34-- "Streamly.Internal.FileSystem.Handle" module.
36-- Design notes:
37--
38-- By design, file handle IO APIs are quite similar to
39-- "Streamly.Data.Array" read write APIs. In that regard, arrays can be
40-- considered as in-memory files or files can be considered as on-disk arrays.
41--
42module Streamly.FileSystem.Handle
43 (
44 -- * Setup
45 -- | To execute the code examples provided in this module in ghci, please
46 -- run the following commands first.
47 --
48 -- $setup
50 -- * Singleton IO
51 -- | Read or write a single buffer.
52 getChunk
53 , putChunk
55 -- * Streaming IO
56 -- | Read or write a stream of data to or from a file or device
57 -- sequentially.
58 --
59 -- Read requests to the IO device are performed in chunks limited to a
60 -- maximum size of 'Streamly.Internal.System.IO.defaultChunkSize'. Note
61 -- that the size of the actual chunks in the resulting stream may be less
62 -- than the @defaultChunkSize@ but it can never exceed it. If the whole
63 -- stream is not consumed, it is possible that we may have read slightly
64 -- more from the IO device than what the consumer needed.
65 --
66 -- Unless specified otherwise in the API, writes are collected into chunks
67 -- of 'Streamly.Internal.System.IO.defaultChunkSize' before they are
68 -- written to the IO device.
70 -- Internal notes:
71 --
72 -- Streaming APIs work for all kind of devices, seekable or non-seekable;
73 -- including disks, files, memory devices, terminals, pipes, sockets and
74 -- fifos. While random access APIs work only for files or devices that have
75 -- random access or seek capability for example disks, memory devices.
76 -- Devices like terminals, pipes, sockets and fifos do not have random
77 -- access capability.
79 -- ** Reading
80 -- | 'TextEncoding', 'NewLineMode', and 'Buffering' options of the
81 -- underlying handle are ignored. The read occurs from the current seek
82 -- position of the file handle. The stream ends as soon as EOF is
83 -- encountered.
85 -- -- *** Streams
86 -- , read
87 -- , readWith
88 -- , readChunks
89 -- , readChunksWith
91 -- -- *** Unfolds
92 , reader
93 , readerWith
94 , chunkReader
95 , chunkReaderWith
97 -- ** Folds
98 -- | 'TextEncoding', 'NewLineMode', and 'Buffering' options of the
99 -- underlying handle are ignored. The write occurs from the current seek
100 -- position of the file handle. The write behavior depends on the 'IOMode'
101 -- of the handle.
103 , write
104 , writeWith
105 , writeChunks
107 -- * Deprecated
108 , read
109 , readWithBufferOf
110 , readChunks
111 , readChunksWithBufferOf
112 , writeChunksWithBufferOf
113 , writeWithBufferOf
114 )
115where
117import Control.Monad.IO.Class (MonadIO(..))
118import Data.Word (Word8)
119import Streamly.Internal.Data.Array.Type (Array)
120import Streamly.Internal.Data.Unfold.Type (Unfold)
121import System.IO (Handle)
123import Streamly.Internal.FileSystem.Handle hiding (read, readChunks)
124import Prelude hiding (read)
126#include "DocTestFileSystemHandle.hs"
128-- | Same as 'reader'
129--
130{-# DEPRECATED read "Please use 'reader' instead" #-}
131{-# INLINE read #-}
132read :: MonadIO m => Unfold m Handle Word8
133read = reader
135-- | Same as 'chunkReader'
136--
137{-# DEPRECATED readChunks "Please use 'chunkReader' instead" #-}
138{-# INLINE readChunks #-}
139readChunks :: MonadIO m => Unfold m Handle (Array Word8)
140readChunks = chunkReader