git.iko.soy/streamly
on e304abc help sign in
streamly/src/Streamly/FileSystem/Handle.hs
102 lines 3.8 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.Prelude" to create a stream of lines or to split the
21-- 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.Prelude.before' combinator may be used to do that on a streaming
25-- combinator. To restrict the length of read or write use the stream trimming
26-- operations like 'Streamly.Prelude.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.Foreign" 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 , read
79 , readWith
80 , readChunks
81 , readChunksWith
83 -- ** Writing
84 -- | 'TextEncoding', 'NewLineMode', and 'Buffering' options of the
85 -- underlying handle are ignored. The write occurs from the current seek
86 -- position of the file handle. The write behavior depends on the 'IOMode'
87 -- of the handle.
89 , write
90 , writeWith
91 , writeChunks
93 -- * Deprecated
94 , readChunksWithBufferOf
95 , readWithBufferOf
96 , writeChunksWithBufferOf
97 , writeWithBufferOf
98 )
99where
101import Streamly.Internal.FileSystem.Handle
102import Prelude hiding (read)