Foreign/Storable.hs

   1 {-# OPTIONS -fno-implicit-prelude #-}
   2 -----------------------------------------------------------------------------
   3 -- |
   4 -- Module      :  Foreign.Storable
   5 -- Copyright   :  (c) The FFI task force 2001
   6 -- License     :  see libraries/base/LICENSE
   7 --
   8 -- Maintainer  :  ffi@haskell.org
   9 -- Stability   :  provisional
  10 -- Portability :  portable
  11 --
  12 -- The module "Foreign.Storable" provides most elementary support for
  13 -- marshalling and is part of the language-independent portion of the
  14 -- Foreign Function Interface (FFI), and will normally be imported via
  15 -- the "Foreign" module.
  16 --
  17 -----------------------------------------------------------------------------
  18
  19 module Foreign.Storable
  20         ( Storable(
  21              sizeOf,         -- :: a -> Int
  22              alignment,      -- :: a -> Int
  23              peekElemOff,    -- :: Ptr a -> Int      -> IO a
  24              pokeElemOff,    -- :: Ptr a -> Int -> a -> IO ()
  25              peekByteOff,    -- :: Ptr b -> Int      -> IO a
  26              pokeByteOff,    -- :: Ptr b -> Int -> a -> IO ()
  27              peek,           -- :: Ptr a             -> IO a
  28              poke)           -- :: Ptr a        -> a -> IO ()
  29         ) where
  30
  31
  32 import Control.Monad            ( liftM )
  33
  34 #include "MachDeps.h"
  35 #include "config.h"
  36
  37 #ifdef __GLASGOW_HASKELL__
  38 import GHC.Storable
  39 import GHC.Stable       ( StablePtr )
  40 import GHC.Num
  41 import GHC.Int
  42 import GHC.Word
  43 import GHC.Stable
  44 import GHC.Ptr
  45 import GHC.Float
  46 import GHC.Err
  47 import GHC.IOBase
  48 import GHC.Base
  49 #else
  50 import Data.Int
  51 import Data.Word
  52 import Foreign.Ptr
  53 import Foreign.StablePtr
  54 #endif
  55
  56 #ifdef __HUGS__
  57 import Hugs.Prelude
  58 import Hugs.Storable
  59 #endif
  60
  61 {- |
  62 The member functions of this class facilitate writing values of
  63 primitive types to raw memory (which may have been allocated with the
  64 above mentioned routines) and reading values from blocks of raw
  65 memory.  The class, furthermore, includes support for computing the
  66 storage requirements and alignment restrictions of storable types.
  67
  68 Memory addresses are represented as values of type @'Ptr' a@, for some
  69 @a@ which is an instance of class 'Storable'.  The type argument to
  70 'Ptr' helps provide some valuable type safety in FFI code (you can\'t
  71 mix pointers of different types without an explicit cast), while
  72 helping the Haskell type system figure out which marshalling method is
  73 needed for a given pointer.
  74
  75 All marshalling between Haskell and a foreign language ultimately
  76 boils down to translating Haskell data structures into the binary
  77 representation of a corresponding data structure of the foreign
  78 language and vice versa.  To code this marshalling in Haskell, it is
  79 necessary to manipulate primtive data types stored in unstructured
  80 memory blocks.  The class 'Storable' facilitates this manipulation on
  81 all types for which it is instantiated, which are the standard basic
  82 types of Haskell, the fixed size @Int@ types ('Int8', 'Int16',
  83 'Int32', 'Int64'), the fixed size @Word@ types ('Word8', 'Word16',
  84 'Word32', 'Word64'), 'StablePtr', all types from "CTypes" and
  85 "CTypesISO", as well as 'Ptr'.
  86
  87 Minimal complete definition: 'sizeOf', 'alignment', one of 'peek',
  88 'peekElemOff' and 'peekByteOff', and one of 'poke', 'pokeElemOff' and
  89 'pokeByteOff'.
  90 -}
  91
  92 class Storable a where
  93
  94    sizeOf      :: a -> Int
  95    -- ^ Computes the storage requirements (in bytes) of the argument.
  96    -- The value of the argument is not used.
  97
  98    alignment   :: a -> Int
  99    -- ^ Computes the alignment constraint of the argument.  An
 100    -- alignment constraint @x@ is fulfilled by any address divisible
 101    -- by @x@.  The value of the argument is not used.
 102
 103    peekElemOff :: Ptr a -> Int      -> IO a
 104    -- ^       Read a value from a memory area regarded as an array
 105    --         of values of the same kind.  The first argument specifies
 106    --         the start address of the array and the second the index into
 107    --         the array (the first element of the array has index
 108    --         @0@).  The following equality holds,
 109    --
 110    -- > peekElemOff addr idx = IOExts.fixIO $ \result ->
 111    -- >   peek (addr \`plusPtr\` (idx * sizeOf result))
 112    --
 113    --         Note that this is only a specification, not
 114    --         necessarily the concrete implementation of the
 115    --         function.
 116
 117    pokeElemOff :: Ptr a -> Int -> a -> IO ()
 118    -- ^       Write a value to a memory area regarded as an array of
 119    --         values of the same kind.  The following equality holds:
 120    --
 121    -- > pokeElemOff addr idx x =
 122    -- >   poke (addr \`plusPtr\` (idx * sizeOf x)) x
 123
 124    peekByteOff :: Ptr b -> Int      -> IO a
 125    -- ^       Read a value from a memory location given by a base
 126    --         address and offset.  The following equality holds:
 127    --
 128    -- > peekByteOff addr off = peek (addr \`plusPtr\` off)
 129
 130    pokeByteOff :: Ptr b -> Int -> a -> IO ()
 131    -- ^       Write a value to a memory location given by a base
 132    --         address and offset.  The following equality holds:
 133    --
 134    -- > pokeByteOff addr off x = poke (addr \`plusPtr\` off) x
 135
 136    peek        :: Ptr a      -> IO a
 137    -- ^ Read a value from the given memory location.
 138    --
 139    --  Note that the peek and poke functions might require properly
 140    --  aligned addresses to function correctly.  This is architecture
 141    --  dependent; thus, portable code should ensure that when peeking or
 142    --  poking values of some type @a@, the alignment
 143    --  constraint for @a@, as given by the function
 144    --  'alignment' is fulfilled.
 145
 146    poke        :: Ptr a -> a -> IO ()
 147    -- ^ Write the given value to the given memory location.  Alignment
 148    -- restrictions might apply; see 'peek'.
 149
 150    -- circular default instances
 151 #ifdef __GLASGOW_HASKELL__
 152    peekElemOff = peekElemOff_ undefined
 153       where peekElemOff_ :: a -> Ptr a -> Int -> IO a
 154             peekElemOff_ undef ptr off = peekByteOff ptr (off * sizeOf undef)
 155 #else
 156    peekElemOff ptr off = peekByteOff ptr (off * sizeOfPtr ptr undefined)
 157 #endif
 158    pokeElemOff ptr off val = pokeByteOff ptr (off * sizeOf val) val
 159
 160    peekByteOff ptr off = peek (ptr `plusPtr` off)
 161    pokeByteOff ptr off = poke (ptr `plusPtr` off)
 162
 163    peek ptr = peekElemOff ptr 0
 164    poke ptr = pokeElemOff ptr 0
 165
 166 #ifndef __GLASGOW_HASKELL__
 167 sizeOfPtr :: Storable a => Ptr a -> a -> Int
 168 sizeOfPtr px x = sizeOf x
 169 #endif
 170
 171 -- System-dependent, but rather obvious instances
 172
 173 instance Storable Bool where
 174    sizeOf _          = sizeOf (undefined::HTYPE_INT)
 175    alignment _       = alignment (undefined::HTYPE_INT)
 176    peekElemOff p i   = liftM (/= (0::HTYPE_INT)) $ peekElemOff (castPtr p) i
 177    pokeElemOff p i x = pokeElemOff (castPtr p) i (if x then 1 else 0::HTYPE_INT)
 178
 179 #define STORABLE(T,size,align,read,write)       \
 180 instance Storable (T) where {                   \
 181     sizeOf    _ = size;                         \
 182     alignment _ = align;                        \
 183     peekElemOff = read;                         \
 184     pokeElemOff = write }
 185
 186 #ifdef __GLASGOW_HASKELL__
 187 STORABLE(Char,SIZEOF_INT32,ALIGNMENT_INT32,
 188          readWideCharOffPtr,writeWideCharOffPtr)
 189 #elif defined(__HUGS__)
 190 STORABLE(Char,SIZEOF_CHAR,ALIGNMENT_HSCHAR,
 191          readCharOffPtr,writeCharOffPtr)
 192 #endif
 193
 194 STORABLE(Int,SIZEOF_HSINT,ALIGNMENT_HSINT,
 195          readIntOffPtr,writeIntOffPtr)
 196
 197 #ifdef __GLASGOW_HASKELL__
 198 STORABLE(Word,SIZEOF_HSWORD,ALIGNMENT_HSWORD,
 199          readWordOffPtr,writeWordOffPtr)
 200 #endif
 201
 202 STORABLE((Ptr a),SIZEOF_HSPTR,ALIGNMENT_HSPTR,
 203          readPtrOffPtr,writePtrOffPtr)
 204
 205 STORABLE((FunPtr a),SIZEOF_HSFUNPTR,ALIGNMENT_HSFUNPTR,
 206          readFunPtrOffPtr,writeFunPtrOffPtr)
 207
 208 STORABLE((StablePtr a),SIZEOF_HSSTABLEPTR,ALIGNMENT_HSSTABLEPTR,
 209          readStablePtrOffPtr,writeStablePtrOffPtr)
 210
 211 STORABLE(Float,SIZEOF_HSFLOAT,ALIGNMENT_HSFLOAT,
 212          readFloatOffPtr,writeFloatOffPtr)
 213
 214 STORABLE(Double,SIZEOF_HSDOUBLE,ALIGNMENT_HSDOUBLE,
 215          readDoubleOffPtr,writeDoubleOffPtr)
 216
 217 STORABLE(Word8,SIZEOF_WORD8,ALIGNMENT_WORD8,
 218          readWord8OffPtr,writeWord8OffPtr)
 219
 220 STORABLE(Word16,SIZEOF_WORD16,ALIGNMENT_WORD16,
 221          readWord16OffPtr,writeWord16OffPtr)
 222
 223 STORABLE(Word32,SIZEOF_WORD32,ALIGNMENT_WORD32,
 224          readWord32OffPtr,writeWord32OffPtr)
 225
 226 STORABLE(Word64,SIZEOF_WORD64,ALIGNMENT_WORD64,
 227          readWord64OffPtr,writeWord64OffPtr)
 228
 229 STORABLE(Int8,SIZEOF_INT8,ALIGNMENT_INT8,
 230          readInt8OffPtr,writeInt8OffPtr)
 231
 232 STORABLE(Int16,SIZEOF_INT16,ALIGNMENT_INT16,
 233          readInt16OffPtr,writeInt16OffPtr)
 234
 235 STORABLE(Int32,SIZEOF_INT32,ALIGNMENT_INT32,
 236          readInt32OffPtr,writeInt32OffPtr)
 237
 238 STORABLE(Int64,SIZEOF_INT64,ALIGNMENT_INT64,
 239          readInt64OffPtr,writeInt64OffPtr)