GHC/IO/BufferedIO.hs

   1 {-# OPTIONS_GHC  -XNoImplicitPrelude -funbox-strict-fields #-}
   2 {-# OPTIONS_HADDOCK hide #-}
   3 -----------------------------------------------------------------------------
   4 -- |
   5 -- Module      :  GHC.IO.BufferedIO
   6 -- Copyright   :  (c) The University of Glasgow 2008
   7 -- License     :  see libraries/base/LICENSE
   8 --
   9 -- Maintainer  :  cvs-ghc@haskell.org
  10 -- Stability   :  internal
  11 -- Portability :  non-portable (GHC Extensions)
  12 --
  13 -- Class of buffered IO devices
  14 --
  15 -----------------------------------------------------------------------------
  16
  17 module GHC.IO.BufferedIO (
  18    BufferedIO(..),
  19    readBuf, readBufNonBlocking, writeBuf, writeBufNonBlocking
  20  ) where
  21
  22 import GHC.Base
  23 import GHC.Ptr
  24 import Data.Word
  25 import GHC.Num
  26 import GHC.Real
  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) (fromIntegral bytes)
  98   let res' = fromIntegral res
  99   return (res', bbuf{ bufR = bufR bbuf + res' })
 100          -- zero indicates end of file
 101
 102 readBufNonBlocking :: RawIO dev => dev -> Buffer Word8
 103                      -> IO (Maybe Int,   -- Nothing ==> end of file
 104                                          -- Just n  ==> n bytes were read (n>=0)
 105                             Buffer Word8)
 106 readBufNonBlocking dev bbuf = do
 107   let bytes = bufferAvailable bbuf
 108   res <- withBuffer bbuf $ \ptr ->
 109            IODevice.readNonBlocking dev (ptr `plusPtr` bufR bbuf) (fromIntegral bytes)
 110   case res of
 111      Nothing -> return (Nothing, bbuf)
 112      Just n  -> return (Just n, bbuf{ bufR = bufR bbuf + fromIntegral n })
 113
 114 writeBuf :: RawIO dev => dev -> Buffer Word8 -> IO (Buffer Word8)
 115 writeBuf dev bbuf = do
 116   let bytes = bufferElems bbuf
 117   withBuffer bbuf $ \ptr ->
 118       IODevice.write dev (ptr `plusPtr` bufL bbuf) (fromIntegral bytes)
 119   return bbuf{ bufL=0, bufR=0 }
 120
 121 -- XXX ToDo
 122 writeBufNonBlocking :: RawIO dev => dev -> Buffer Word8 -> IO (Int, Buffer Word8)
 123 writeBufNonBlocking dev bbuf = do
 124   let bytes = bufferElems bbuf
 125   res <- withBuffer bbuf $ \ptr ->
 126             IODevice.writeNonBlocking dev (ptr `plusPtr` bufL bbuf)
 127                                       (fromIntegral bytes)
 128   return (res, bufferAdjustL res bbuf)