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