git.iko.soy/streamly
on defafa6 help sign in
streamly/core/src/Streamly/FileSystem/Handle.hs
117 lines 4.1 kB history raw
1{-# LANGUAGE CPP #-}
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.Stream"
19-- module 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 -- * Setup
44 -- | To execute the code examples provided in this module in ghci, please
45 -- run the following commands first.
46 --
47 -- $setup
49 -- * Singleton IO
50 -- | Read or write a single buffer.
51 getChunk
52 , putChunk
54 -- * Streaming IO
55 -- | Read or write a stream of data to or from a file or device
56 -- sequentially.
57 --
58 -- Read requests to the IO device are performed in chunks limited to a
59 -- maximum size of 'Streamly.Internal.System.IO.defaultChunkSize'. Note
60 -- that the size of the actual chunks in the resulting stream may be less
61 -- than the @defaultChunkSize@ but it can never exceed it. If the whole
62 -- stream is not consumed, it is possible that we may have read slightly
63 -- more from the IO device than what the consumer needed.
64 --
65 -- Unless specified otherwise in the API, writes are collected into chunks
66 -- of 'Streamly.Internal.System.IO.defaultChunkSize' before they are
67 -- written to the IO device.
69 -- Internal notes:
70 --
71 -- Streaming APIs work for all kind of devices, seekable or non-seekable;
72 -- including disks, files, memory devices, terminals, pipes, sockets and
73 -- fifos. While random access APIs work only for files or devices that have
74 -- random access or seek capability for example disks, memory devices.
75 -- Devices like terminals, pipes, sockets and fifos do not have random
76 -- access capability.
78 -- ** Reading
79 -- | 'TextEncoding', 'NewLineMode', and 'Buffering' options of the
80 -- underlying handle are ignored. The read occurs from the current seek
81 -- position of the file handle. The stream ends as soon as EOF is
82 -- encountered.
84 -- *** Streams
85 , read
86 , readWith
87 , readChunks
88 , readChunksWith
90 -- *** Unfolds
91 , reader
92 , readerWith
93 , chunkReader
94 , chunkReaderWith
96 -- ** Folds
97 -- | 'TextEncoding', 'NewLineMode', and 'Buffering' options of the
98 -- underlying handle are ignored. The write occurs from the current seek
99 -- position of the file handle. The write behavior depends on the 'IOMode'
100 -- of the handle.
102 , write
103 , writeWith
104 , writeChunks
106 -- * Deprecated
107 , readWithBufferOf
108 , readChunksWithBufferOf
109 , writeChunksWithBufferOf
110 , writeWithBufferOf
111 )
112where
114import Streamly.Internal.FileSystem.Handle
115import Prelude hiding (read)
117#include "DocTestFileSystemHandle.hs"