874a02d1dcf56c13aa20c3e0c7bfe161cd11f314
[packages/base.git] / GHC / IO / BufferedIO.hs
1 {-# LANGUAGE NoImplicitPrelude #-}
2 {-# OPTIONS_GHC -funbox-strict-fields #-}
3
4 -----------------------------------------------------------------------------
5 -- |
6 -- Module : GHC.IO.BufferedIO
7 -- Copyright : (c) The University of Glasgow 2008
8 -- License : see libraries/base/LICENSE
9 --
10 -- Maintainer : cvs-ghc@haskell.org
11 -- Stability : internal
12 -- Portability : non-portable (GHC Extensions)
13 --
14 -- Class of buffered IO devices
15 --
16 -----------------------------------------------------------------------------
17
18 module GHC.IO.BufferedIO (
19 BufferedIO(..),
20 readBuf, readBufNonBlocking, writeBuf, writeBufNonBlocking
21 ) where
22
23 import GHC.Base
24 import GHC.Ptr
25 import Data.Word
26 import GHC.Num
27 import Data.Maybe
28 -- import GHC.IO
29 import GHC.IO.Device as IODevice
30 import GHC.IO.Device as RawIO
31 import GHC.IO.Buffer
32
33 -- | The purpose of 'BufferedIO' is to provide a common interface for I/O
34 -- devices that can read and write data through a buffer. Devices that
35 -- implement 'BufferedIO' include ordinary files, memory-mapped files,
36 -- and bytestrings. The underlying device implementing a 'Handle' must
37 -- provide 'BufferedIO'.
38 --
39 class BufferedIO dev where
40 -- | allocate a new buffer. The size of the buffer is at the
41 -- discretion of the device; e.g. for a memory-mapped file the
42 -- buffer will probably cover the entire file.
43 newBuffer :: dev -> BufferState -> IO (Buffer Word8)
44
45 -- | reads bytes into the buffer, blocking if there are no bytes
46 -- available. Returns the number of bytes read (zero indicates
47 -- end-of-file), and the new buffer.
48 fillReadBuffer :: dev -> Buffer Word8 -> IO (Int, Buffer Word8)
49
50 -- | reads bytes into the buffer without blocking. Returns the
51 -- number of bytes read (Nothing indicates end-of-file), and the new
52 -- buffer.
53 fillReadBuffer0 :: dev -> Buffer Word8 -> IO (Maybe Int, Buffer Word8)
54
55 -- | Prepares an empty write buffer. This lets the device decide
56 -- how to set up a write buffer: the buffer may need to point to a
57 -- specific location in memory, for example. This is typically used
58 -- by the client when switching from reading to writing on a
59 -- buffered read/write device.
60 --
61 -- There is no corresponding operation for read buffers, because before
62 -- reading the client will always call 'fillReadBuffer'.
63 emptyWriteBuffer :: dev -> Buffer Word8 -> IO (Buffer Word8)
64 emptyWriteBuffer _dev buf
65 = return buf{ bufL=0, bufR=0, bufState = WriteBuffer }
66
67 -- | Flush all the data from the supplied write buffer out to the device.
68 -- The returned buffer should be empty, and ready for writing.
69 flushWriteBuffer :: dev -> Buffer Word8 -> IO (Buffer Word8)
70
71 -- | Flush data from the supplied write buffer out to the device
72 -- without blocking. Returns the number of bytes written and the
73 -- remaining buffer.
74 flushWriteBuffer0 :: dev -> Buffer Word8 -> IO (Int, Buffer Word8)
75
76 -- for an I/O device, these operations will perform reading/writing
77 -- to/from the device.
78
79 -- for a memory-mapped file, the buffer will be the whole file in
80 -- memory. fillReadBuffer sets the pointers to encompass the whole
81 -- file, and flushWriteBuffer needs to do no I/O. A memory-mapped
82 -- file has to maintain its own file pointer.
83
84 -- for a bytestring, again the buffer should match the bytestring in
85 -- memory.
86
87 -- ---------------------------------------------------------------------------
88 -- Low-level read/write to/from buffers
89
90 -- These operations make it easy to implement an instance of 'BufferedIO'
91 -- for an object that supports 'RawIO'.
92
93 readBuf :: RawIO dev => dev -> Buffer Word8 -> IO (Int, Buffer Word8)
94 readBuf dev bbuf = do
95 let bytes = bufferAvailable bbuf
96 res <- withBuffer bbuf $ \ptr ->
97 RawIO.read dev (ptr `plusPtr` bufR bbuf) bytes
98 return (res, bbuf{ bufR = bufR bbuf + res })
99 -- zero indicates end of file
100
101 readBufNonBlocking :: RawIO dev => dev -> Buffer Word8
102 -> IO (Maybe Int, -- Nothing ==> end of file
103 -- Just n ==> n bytes were read (n>=0)
104 Buffer Word8)
105 readBufNonBlocking dev bbuf = do
106 let bytes = bufferAvailable bbuf
107 res <- withBuffer bbuf $ \ptr ->
108 IODevice.readNonBlocking dev (ptr `plusPtr` bufR bbuf) bytes
109 case res of
110 Nothing -> return (Nothing, bbuf)
111 Just n -> return (Just n, bbuf{ bufR = bufR bbuf + n })
112
113 writeBuf :: RawIO dev => dev -> Buffer Word8 -> IO (Buffer Word8)
114 writeBuf dev bbuf = do
115 let bytes = bufferElems bbuf
116 withBuffer bbuf $ \ptr ->
117 IODevice.write dev (ptr `plusPtr` bufL bbuf) bytes
118 return bbuf{ bufL=0, bufR=0 }
119
120 -- XXX ToDo
121 writeBufNonBlocking :: RawIO dev => dev -> Buffer Word8 -> IO (Int, Buffer Word8)
122 writeBufNonBlocking dev bbuf = do
123 let bytes = bufferElems bbuf
124 res <- withBuffer bbuf $ \ptr ->
125 IODevice.writeNonBlocking dev (ptr `plusPtr` bufL bbuf) bytes
126 return (res, bufferAdjustL res bbuf)