ghc/docs/libraries/Foreign.sgml

   1 <sect> <idx/Foreign/
   2 <label id="sec:Foreign">
   3 <p>
   4
   5 This module provides the <tt/ForeignObj/ type, which is a Haskell
   6 reference to an object in the outside world.  Foreign objects are
   7 boxed versions of <tt/Addr#/, the only reason for their existence is
   8 so that they can be used with finalisers (see Section <ref
   9 id="foreign-finalisers" name="Finalisation for foreign objects">).
  10
  11 <tscreen><verb>
  12 module Foreign where
  13 data ForeignObj  -- abstract, instance of: Eq
  14
  15 makeForeignObj      :: Addr{-object-} -> Addr{-finaliser-} -> IO ForeignObj
  16 writeForeignObj     :: ForeignObj -> Addr{-new value-} -> IO ()
  17 mkForeignObj        :: Addr -> IO ForeignObj
  18 addForeignFinalizer :: ForeignObj -> IO () -> IO ()
  19 </verb> </tscreen>
  20
  21 In addition to the above, the following operations for indexing via
  22 a <tt/ForeignObj/ are also, mirrored on the same operations provided
  23 over <tt/Addr/s:
  24
  25 <tscreen><verb>
  26 indexCharOffForeignObj   :: ForeignObj -> Int -> Char
  27 indexIntOffForeignObj    :: ForeignObj -> Int -> Int
  28 indexWordOffForeignObj   :: ForeignObj -> Int -> Word
  29 indexAddrOffForeignObj   :: ForeignObj -> Int -> Addr
  30 indexFloatOffForeignObj  :: ForeignObj -> Int -> Float
  31 indexDoubleOffForeignObj :: ForeignObj -> Int -> Double
  32 indexWord8OffForeignObj  :: ForeignObj -> Int -> Word8
  33 indexWord16OffForeignObj :: ForeignObj -> Int -> Word16
  34 indexWord32OffForeignObj :: ForeignObj -> Int -> Word32
  35 indexWord64OffForeignObj :: ForeignObj -> Int -> Word64
  36
  37 indexInt8OffForeignObj  :: ForeignObj -> Int -> Int8
  38 indexInt16OffForeignObj :: ForeignObj -> Int -> Int16
  39 indexInt32OffForeignObj :: ForeignObj -> Int -> Int32
  40 indexInt64OffForeignObj :: ForeignObj -> Int -> Int64
  41
  42 -- read value out of mutable memory
  43 readCharOffForeignObj    :: ForeignObj -> Int -> IO Char
  44 readIntOffForeignObj     :: ForeignObj -> Int -> IO Int
  45 readWordOffForeignObj    :: ForeignObj -> Int -> IO Word
  46 readAddrOffForeignObj    :: ForeignObj -> Int -> IO Addr
  47 readFloatOffForeignObj   :: ForeignObj -> Int -> IO Float
  48 readDoubleOffForeignObj  :: ForeignObj -> Int -> IO Double
  49 readWord8OffForeignObj   :: ForeignObj -> Int -> IO Word8
  50 readWord16OffForeignObj  :: ForeignObj -> Int -> IO Word16
  51 readWord32OffForeignObj  :: ForeignObj -> Int -> IO Word32
  52 readWord64OffForeignObj  :: ForeignObj -> Int -> IO Word64
  53 readInt8OffForeignObj    :: ForeignObj -> Int -> IO Int8
  54 readInt16OffForeignObj   :: ForeignObj -> Int -> IO Int16
  55 readInt32OffForeignObj   :: ForeignObj -> Int -> IO Int32
  56 readInt64OffForeignObj   :: ForeignObj -> Int -> IO Int64
  57
  58 writeCharOffForeignObj   :: ForeignObj -> Int -> Char   -> IO ()
  59 writeIntOffForeignObj    :: ForeignObj -> Int -> Int    -> IO ()
  60 writeWordOffForeignObj   :: ForeignObj -> Int -> Word   -> IO ()
  61 writeAddrOffForeignObj   :: ForeignObj -> Int -> Addr   -> IO ()
  62 writeFloatOffForeignObj  :: ForeignObj -> Int -> Float  -> IO ()
  63 writeDoubleOffForeignObj :: ForeignObj -> Int -> Double -> IO ()
  64 writeWord8OffForeignObj  :: ForeignObj -> Int -> Word8  -> IO ()
  65 writeWord16OffForeignObj :: ForeignObj -> Int -> Word16 -> IO ()
  66 writeWord32OffForeignObj :: ForeignObj -> Int -> Word32 -> IO ()
  67 writeWord64OffForeignObj :: ForeignObj -> Int -> Word64 -> IO ()
  68 writeInt8OffForeignObj   :: ForeignObj -> Int -> Int8   -> IO ()
  69 writeInt16OffForeignObj  :: ForeignObj -> Int -> Int16  -> IO ()
  70 writeInt32OffForeignObj  :: ForeignObj -> Int -> Int32  -> IO ()
  71 writeInt64OffForeignObj  :: ForeignObj -> Int -> Int64  -> IO ()
  72 </verb></tscreen>
  73