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-} -> IO ForeignObj
  16 writeForeignObj :: ForeignObj -> Addr{-new value-} -> IO ()
  17 </verb> </tscreen>
  18
  19 In addition to the above, the following operations for indexing via
  20 a <tt/ForeignObj/ are also, mirrored on the same operations provided
  21 over <tt/Addr/s:
  22
  23 <tscreen><verb>
  24 indexCharOffForeignObj   :: ForeignObj -> Int -> Char
  25 indexIntOffForeignObj    :: ForeignObj -> Int -> Int
  26 indexAddrOffForeignObj   :: ForeignObj -> Int -> Addr
  27 indexFloatOffForeignObj  :: ForeignObj -> Int -> Float
  28 indexDoubleOffForeignObj :: ForeignObj -> Int -> Double
  29 indexWord8OffForeignObj  :: ForeignObj -> Int -> Word8
  30 indexWord16OffForeignObj :: ForeignObj -> Int -> Word16
  31 indexWord32OffForeignObj :: ForeignObj -> Int -> Word32
  32 indexWord64OffForeignObj :: ForeignObj -> Int -> Word64
  33
  34 indexInt8OffForeignObj  :: ForeignObj -> Int -> Int8
  35 indexInt16OffForeignObj :: ForeignObj -> Int -> Int16
  36 indexInt32OffForeignObj :: ForeignObj -> Int -> Int32
  37 indexInt64OffForeignObj :: ForeignObj -> Int -> Int64
  38
  39 -- read value out of mutable memory
  40 readCharOffForeignObj    :: ForeignObj -> Int -> IO Char
  41 readIntOffForeignObj     :: ForeignObj -> Int -> IO Int
  42 readAddrOffForeignObj    :: ForeignObj -> Int -> IO Addr
  43 readFloatOffForeignObj   :: ForeignObj -> Int -> IO Float
  44 readDoubleOffForeignObj  :: ForeignObj -> Int -> IO Double
  45 readWord8OffForeignObj   :: ForeignObj -> Int -> IO Word8
  46 readWord16OffForeignObj  :: ForeignObj -> Int -> IO Word16
  47 readWord32OffForeignObj  :: ForeignObj -> Int -> IO Word32
  48 readWord64OffForeignObj  :: ForeignObj -> Int -> IO Word64
  49 readInt8OffForeignObj    :: ForeignObj -> Int -> IO Int8
  50 readInt16OffForeignObj   :: ForeignObj -> Int -> IO Int16
  51 readInt32OffForeignObj   :: ForeignObj -> Int -> IO Int32
  52 readInt64OffForeignObj   :: ForeignObj -> Int -> IO Int64
  53
  54 writeCharOffForeignObj   :: ForeignObj -> Int -> Char   -> IO ()
  55 writeIntOffForeignObj    :: ForeignObj -> Int -> Int    -> IO ()
  56 writeAddrOffForeignObj   :: ForeignObj -> Int -> Addr   -> IO ()
  57 writeFloatOffForeignObj  :: ForeignObj -> Int -> Float  -> IO ()
  58 writeDoubleOffForeignObj :: ForeignObj -> Int -> Double -> IO ()
  59 writeWord8OffForeignObj  :: ForeignObj -> Int -> Word8  -> IO ()
  60 writeWord16OffForeignObj :: ForeignObj -> Int -> Word16 -> IO ()
  61 writeWord32OffForeignObj :: ForeignObj -> Int -> Word32 -> IO ()
  62 writeWord64OffForeignObj :: ForeignObj -> Int -> Word64 -> IO ()
  63 writeInt8OffForeignObj   :: ForeignObj -> Int -> Int8   -> IO ()
  64 writeInt16OffForeignObj  :: ForeignObj -> Int -> Int16  -> IO ()
  65 writeInt32OffForeignObj  :: ForeignObj -> Int -> Int32  -> IO ()
  66 writeInt64OffForeignObj  :: ForeignObj -> Int -> Int64  -> IO ()
  67 </verb></tscreen>
  68