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