8f739810c437cf8a4e282e7760d1a1c47b5d63c3
[ghc.git] / libraries / base / GHC / IO / Handle / Types.hs
1 {-# LANGUAGE Trustworthy #-}
2 {-# LANGUAGE CPP
3 , NoImplicitPrelude
4 , ExistentialQuantification
5 #-}
6 {-# OPTIONS_GHC -funbox-strict-fields #-}
7 {-# OPTIONS_HADDOCK hide #-}
8
9 -----------------------------------------------------------------------------
10 -- |
11 -- Module : GHC.IO.Handle.Types
12 -- Copyright : (c) The University of Glasgow, 1994-2009
13 -- License : see libraries/base/LICENSE
14 --
15 -- Maintainer : libraries@haskell.org
16 -- Stability : internal
17 -- Portability : non-portable
18 --
19 -- Basic types for the implementation of IO Handles.
20 --
21 -----------------------------------------------------------------------------
22
23 module GHC.IO.Handle.Types (
24 Handle(..), Handle__(..), showHandle,
25 checkHandleInvariants,
26 BufferList(..),
27 HandleType(..),
28 isReadableHandleType, isWritableHandleType, isReadWriteHandleType,
29 BufferMode(..),
30 BufferCodec(..),
31 NewlineMode(..), Newline(..), nativeNewline,
32 universalNewlineMode, noNewlineTranslation, nativeNewlineMode
33 ) where
34
35 #undef DEBUG
36
37 import GHC.Base
38 import GHC.MVar
39 import GHC.IO
40 import GHC.IO.Buffer
41 import GHC.IO.BufferedIO
42 import GHC.IO.Encoding.Types
43 import GHC.IORef
44 import GHC.Show
45 import GHC.Read
46 import GHC.Word
47 import GHC.IO.Device
48 import Data.Typeable
49 #ifdef DEBUG
50 import Control.Monad
51 #endif
52
53 -- ---------------------------------------------------------------------------
54 -- Handle type
55
56 -- A Handle is represented by (a reference to) a record
57 -- containing the state of the I/O port/device. We record
58 -- the following pieces of info:
59
60 -- * type (read,write,closed etc.)
61 -- * the underlying file descriptor
62 -- * buffering mode
63 -- * buffer, and spare buffers
64 -- * user-friendly name (usually the
65 -- FilePath used when IO.openFile was called)
66
67 -- Note: when a Handle is garbage collected, we want to flush its buffer
68 -- and close the OS file handle, so as to free up a (precious) resource.
69
70 -- | Haskell defines operations to read and write characters from and to files,
71 -- represented by values of type @Handle@. Each value of this type is a
72 -- /handle/: a record used by the Haskell run-time system to /manage/ I\/O
73 -- with file system objects. A handle has at least the following properties:
74 --
75 -- * whether it manages input or output or both;
76 --
77 -- * whether it is /open/, /closed/ or /semi-closed/;
78 --
79 -- * whether the object is seekable;
80 --
81 -- * whether buffering is disabled, or enabled on a line or block basis;
82 --
83 -- * a buffer (whose length may be zero).
84 --
85 -- Most handles will also have a current I\/O position indicating where the next
86 -- input or output operation will occur. A handle is /readable/ if it
87 -- manages only input or both input and output; likewise, it is /writable/ if
88 -- it manages only output or both input and output. A handle is /open/ when
89 -- first allocated.
90 -- Once it is closed it can no longer be used for either input or output,
91 -- though an implementation cannot re-use its storage while references
92 -- remain to it. Handles are in the 'Show' and 'Eq' classes. The string
93 -- produced by showing a handle is system dependent; it should include
94 -- enough information to identify the handle for debugging. A handle is
95 -- equal according to '==' only to itself; no attempt
96 -- is made to compare the internal state of different handles for equality.
97
98 data Handle
99 = FileHandle -- A normal handle to a file
100 FilePath -- the file (used for error messages
101 -- only)
102 !(MVar Handle__)
103
104 | DuplexHandle -- A handle to a read/write stream
105 FilePath -- file for a FIFO, otherwise some
106 -- descriptive string (used for error
107 -- messages only)
108 !(MVar Handle__) -- The read side
109 !(MVar Handle__) -- The write side
110
111 -- NOTES:
112 -- * A 'FileHandle' is seekable. A 'DuplexHandle' may or may not be
113 -- seekable.
114
115 -- | @since 4.1.0.0
116 instance Eq Handle where
117 (FileHandle _ h1) == (FileHandle _ h2) = h1 == h2
118 (DuplexHandle _ h1 _) == (DuplexHandle _ h2 _) = h1 == h2
119 _ == _ = False
120
121 data Handle__
122 = forall dev enc_state dec_state . (IODevice dev, BufferedIO dev, Typeable dev) =>
123 Handle__ {
124 haDevice :: !dev,
125 haType :: HandleType, -- type (read/write/append etc.)
126 haByteBuffer :: !(IORef (Buffer Word8)), -- See [note Buffering Implementation]
127 haBufferMode :: BufferMode,
128 haLastDecode :: !(IORef (dec_state, Buffer Word8)),
129 haCharBuffer :: !(IORef (Buffer CharBufElem)), -- See [note Buffering Implementation]
130 haBuffers :: !(IORef (BufferList CharBufElem)), -- spare buffers
131 haEncoder :: Maybe (TextEncoder enc_state),
132 haDecoder :: Maybe (TextDecoder dec_state),
133 haCodec :: Maybe TextEncoding,
134 haInputNL :: Newline,
135 haOutputNL :: Newline,
136 haOtherSide :: Maybe (MVar Handle__) -- ptr to the write side of a
137 -- duplex handle.
138 }
139
140 -- we keep a few spare buffers around in a handle to avoid allocating
141 -- a new one for each hPutStr. These buffers are *guaranteed* to be the
142 -- same size as the main buffer.
143 data BufferList e
144 = BufferListNil
145 | BufferListCons (RawBuffer e) (BufferList e)
146
147 -- Internally, we classify handles as being one
148 -- of the following:
149
150 data HandleType
151 = ClosedHandle
152 | SemiClosedHandle
153 | ReadHandle
154 | WriteHandle
155 | AppendHandle
156 | ReadWriteHandle
157
158 isReadableHandleType :: HandleType -> Bool
159 isReadableHandleType ReadHandle = True
160 isReadableHandleType ReadWriteHandle = True
161 isReadableHandleType _ = False
162
163 isWritableHandleType :: HandleType -> Bool
164 isWritableHandleType AppendHandle = True
165 isWritableHandleType WriteHandle = True
166 isWritableHandleType ReadWriteHandle = True
167 isWritableHandleType _ = False
168
169 isReadWriteHandleType :: HandleType -> Bool
170 isReadWriteHandleType ReadWriteHandle{} = True
171 isReadWriteHandleType _ = False
172
173 -- INVARIANTS on Handles:
174 --
175 -- * A handle *always* has a buffer, even if it is only 1 character long
176 -- (an unbuffered handle needs a 1 character buffer in order to support
177 -- hLookAhead and hIsEOF).
178 -- * In a read Handle, the byte buffer is always empty (we decode when reading)
179 -- * In a wriite Handle, the Char buffer is always empty (we encode when writing)
180 --
181 checkHandleInvariants :: Handle__ -> IO ()
182 #ifdef DEBUG
183 checkHandleInvariants h_ = do
184 bbuf <- readIORef (haByteBuffer h_)
185 checkBuffer bbuf
186 cbuf <- readIORef (haCharBuffer h_)
187 checkBuffer cbuf
188 when (isWriteBuffer cbuf && not (isEmptyBuffer cbuf)) $
189 errorWithoutStackTrace ("checkHandleInvariants: char write buffer non-empty: " ++
190 summaryBuffer bbuf ++ ", " ++ summaryBuffer cbuf)
191 when (isWriteBuffer bbuf /= isWriteBuffer cbuf) $
192 errorWithoutStackTrace ("checkHandleInvariants: buffer modes differ: " ++
193 summaryBuffer bbuf ++ ", " ++ summaryBuffer cbuf)
194
195 #else
196 checkHandleInvariants _ = return ()
197 #endif
198
199 -- ---------------------------------------------------------------------------
200 -- Buffering modes
201
202 -- | Three kinds of buffering are supported: line-buffering,
203 -- block-buffering or no-buffering. These modes have the following
204 -- effects. For output, items are written out, or /flushed/,
205 -- from the internal buffer according to the buffer mode:
206 --
207 -- * /line-buffering/: the entire output buffer is flushed
208 -- whenever a newline is output, the buffer overflows,
209 -- a 'System.IO.hFlush' is issued, or the handle is closed.
210 --
211 -- * /block-buffering/: the entire buffer is written out whenever it
212 -- overflows, a 'System.IO.hFlush' is issued, or the handle is closed.
213 --
214 -- * /no-buffering/: output is written immediately, and never stored
215 -- in the buffer.
216 --
217 -- An implementation is free to flush the buffer more frequently,
218 -- but not less frequently, than specified above.
219 -- The output buffer is emptied as soon as it has been written out.
220 --
221 -- Similarly, input occurs according to the buffer mode for the handle:
222 --
223 -- * /line-buffering/: when the buffer for the handle is not empty,
224 -- the next item is obtained from the buffer; otherwise, when the
225 -- buffer is empty, characters up to and including the next newline
226 -- character are read into the buffer. No characters are available
227 -- until the newline character is available or the buffer is full.
228 --
229 -- * /block-buffering/: when the buffer for the handle becomes empty,
230 -- the next block of data is read into the buffer.
231 --
232 -- * /no-buffering/: the next input item is read and returned.
233 -- The 'System.IO.hLookAhead' operation implies that even a no-buffered
234 -- handle may require a one-character buffer.
235 --
236 -- The default buffering mode when a handle is opened is
237 -- implementation-dependent and may depend on the file system object
238 -- which is attached to that handle.
239 -- For most implementations, physical files will normally be block-buffered
240 -- and terminals will normally be line-buffered.
241
242 data BufferMode
243 = NoBuffering -- ^ buffering is disabled if possible.
244 | LineBuffering
245 -- ^ line-buffering should be enabled if possible.
246 | BlockBuffering (Maybe Int)
247 -- ^ block-buffering should be enabled if possible.
248 -- The size of the buffer is @n@ items if the argument
249 -- is 'Just' @n@ and is otherwise implementation-dependent.
250 deriving (Eq, Ord, Read, Show)
251
252 {-
253 [note Buffering Implementation]
254
255 Each Handle has two buffers: a byte buffer (haByteBuffer) and a Char
256 buffer (haCharBuffer).
257
258 [note Buffered Reading]
259
260 For read Handles, bytes are read into the byte buffer, and immediately
261 decoded into the Char buffer (see
262 GHC.IO.Handle.Internals.readTextDevice). The only way there might be
263 some data left in the byte buffer is if there is a partial multi-byte
264 character sequence that cannot be decoded into a full character.
265
266 Note that the buffering mode (haBufferMode) makes no difference when
267 reading data into a Handle. When reading, we can always just read all
268 the data there is available without blocking, decode it into the Char
269 buffer, and then provide it immediately to the caller.
270
271 [note Buffered Writing]
272
273 Characters are written into the Char buffer by e.g. hPutStr. At the
274 end of the operation, or when the char buffer is full, the buffer is
275 decoded to the byte buffer (see writeCharBuffer). This is so that we
276 can detect encoding errors at the right point.
277
278 Hence, the Char buffer is always empty between Handle operations.
279
280 [note Buffer Sizing]
281
282 The char buffer is always a default size (dEFAULT_CHAR_BUFFER_SIZE).
283 The byte buffer size is chosen by the underlying device (via its
284 IODevice.newBuffer). Hence the size of these buffers is not under
285 user control.
286
287 There are certain minimum sizes for these buffers imposed by the
288 library (but not checked):
289
290 - we must be able to buffer at least one character, so that
291 hLookAhead can work
292
293 - the byte buffer must be able to store at least one encoded
294 character in the current encoding (6 bytes?)
295
296 - when reading, the char buffer must have room for two characters, so
297 that we can spot the \r\n sequence.
298
299 How do we implement hSetBuffering?
300
301 For reading, we have never used the user-supplied buffer size, because
302 there's no point: we always pass all available data to the reader
303 immediately. Buffering would imply waiting until a certain amount of
304 data is available, which has no advantages. So hSetBuffering is
305 essentially a no-op for read handles, except that it turns on/off raw
306 mode for the underlying device if necessary.
307
308 For writing, the buffering mode is handled by the write operations
309 themselves (hPutChar and hPutStr). Every write ends with
310 writeCharBuffer, which checks whether the buffer should be flushed
311 according to the current buffering mode. Additionally, we look for
312 newlines and flush if the mode is LineBuffering.
313
314 [note Buffer Flushing]
315
316 ** Flushing the Char buffer
317
318 We must be able to flush the Char buffer, in order to implement
319 hSetEncoding, and things like hGetBuf which want to read raw bytes.
320
321 Flushing the Char buffer on a write Handle is easy: it is always empty.
322
323 Flushing the Char buffer on a read Handle involves rewinding the byte
324 buffer to the point representing the next Char in the Char buffer.
325 This is done by
326
327 - remembering the state of the byte buffer *before* the last decode
328
329 - re-decoding the bytes that represent the chars already read from the
330 Char buffer. This gives us the point in the byte buffer that
331 represents the *next* Char to be read.
332
333 In order for this to work, after readTextHandle we must NOT MODIFY THE
334 CONTENTS OF THE BYTE OR CHAR BUFFERS, except to remove characters from
335 the Char buffer.
336
337 ** Flushing the byte buffer
338
339 The byte buffer can be flushed if the Char buffer has already been
340 flushed (see above). For a read Handle, flushing the byte buffer
341 means seeking the device back by the number of bytes in the buffer,
342 and hence it is only possible on a seekable Handle.
343
344 -}
345
346 -- ---------------------------------------------------------------------------
347 -- Newline translation
348
349 -- | The representation of a newline in the external file or stream.
350 data Newline = LF -- ^ '\n'
351 | CRLF -- ^ '\r\n'
352 deriving (Eq, Ord, Read, Show)
353
354 -- | Specifies the translation, if any, of newline characters between
355 -- internal Strings and the external file or stream. Haskell Strings
356 -- are assumed to represent newlines with the '\n' character; the
357 -- newline mode specifies how to translate '\n' on output, and what to
358 -- translate into '\n' on input.
359 data NewlineMode
360 = NewlineMode { inputNL :: Newline,
361 -- ^ the representation of newlines on input
362 outputNL :: Newline
363 -- ^ the representation of newlines on output
364 }
365 deriving (Eq, Ord, Read, Show)
366
367 -- | The native newline representation for the current platform: 'LF'
368 -- on Unix systems, 'CRLF' on Windows.
369 nativeNewline :: Newline
370 #ifdef mingw32_HOST_OS
371 nativeNewline = CRLF
372 #else
373 nativeNewline = LF
374 #endif
375
376 -- | Map '\r\n' into '\n' on input, and '\n' to the native newline
377 -- represetnation on output. This mode can be used on any platform, and
378 -- works with text files using any newline convention. The downside is
379 -- that @readFile >>= writeFile@ might yield a different file.
380 --
381 -- > universalNewlineMode = NewlineMode { inputNL = CRLF,
382 -- > outputNL = nativeNewline }
383 --
384 universalNewlineMode :: NewlineMode
385 universalNewlineMode = NewlineMode { inputNL = CRLF,
386 outputNL = nativeNewline }
387
388 -- | Use the native newline representation on both input and output
389 --
390 -- > nativeNewlineMode = NewlineMode { inputNL = nativeNewline
391 -- > outputNL = nativeNewline }
392 --
393 nativeNewlineMode :: NewlineMode
394 nativeNewlineMode = NewlineMode { inputNL = nativeNewline,
395 outputNL = nativeNewline }
396
397 -- | Do no newline translation at all.
398 --
399 -- > noNewlineTranslation = NewlineMode { inputNL = LF, outputNL = LF }
400 --
401 noNewlineTranslation :: NewlineMode
402 noNewlineTranslation = NewlineMode { inputNL = LF, outputNL = LF }
403
404 -- ---------------------------------------------------------------------------
405 -- Show instance for Handles
406
407 -- handle types are 'show'n when printing error msgs, so
408 -- we provide a more user-friendly Show instance for it
409 -- than the derived one.
410
411 -- | @since 4.1.0.0
412 instance Show HandleType where
413 showsPrec _ t =
414 case t of
415 ClosedHandle -> showString "closed"
416 SemiClosedHandle -> showString "semi-closed"
417 ReadHandle -> showString "readable"
418 WriteHandle -> showString "writable"
419 AppendHandle -> showString "writable (append)"
420 ReadWriteHandle -> showString "read-writable"
421
422 -- | @since 4.1.0.0
423 instance Show Handle where
424 showsPrec _ (FileHandle file _) = showHandle file
425 showsPrec _ (DuplexHandle file _ _) = showHandle file
426
427 showHandle :: FilePath -> String -> String
428 showHandle file = showString "{handle: " . showString file . showString "}"
429