ghc/lib/std/PrelMarshalArray.lhs

   1 % -----------------------------------------------------------------------------
   2 % $Id: PrelMarshalArray.lhs,v 1.3 2001/05/18 16:54:05 simonmar Exp $
   3 %
   4 % (c) The FFI task force, 2000
   5 %
   6
   7 Marshalling support: routines allocating, storing, and retrieving Haskell
   8 lists that are represented as arrays in the foreign language
   9
  10 \begin{code}
  11 {-# OPTIONS -fno-implicit-prelude #-}
  12
  13 module PrelMarshalArray (
  14
  15   -- allocation
  16   --
  17   mallocArray,    -- :: Storable a => Int -> IO (Ptr a)
  18   mallocArray0,   -- :: Storable a => Int -> IO (Ptr a)
  19
  20   allocaArray,    -- :: Storable a => Int -> (Ptr a -> IO b) -> IO b
  21   allocaArray0,   -- :: Storable a => Int -> (Ptr a -> IO b) -> IO b
  22
  23   reallocArray,   -- :: Storable a => Ptr a -> Int -> IO (Ptr a)
  24   reallocArray0,  -- :: Storable a => Ptr a -> Int -> IO (Ptr a)
  25
  26   -- marshalling
  27   --
  28   peekArray,      -- :: Storable a =>         Int -> Ptr a -> IO [a]
  29   peekArray0,     -- :: (Storable a, Eq a) => a   -> Ptr a -> IO [a]
  30
  31   pokeArray,      -- :: Storable a =>      Ptr a -> [a] -> IO ()
  32   pokeArray0,     -- :: Storable a => a -> Ptr a -> [a] -> IO ()
  33
  34   -- combined allocation and marshalling
  35   --
  36   newArray,       -- :: Storable a =>      [a] -> IO (Ptr a)
  37   newArray0,      -- :: Storable a => a -> [a] -> IO (Ptr a)
  38
  39   withArray,      -- :: Storable a =>      [a] -> (Ptr a -> IO b) -> IO b
  40   withArray0,     -- :: Storable a => a -> [a] -> (Ptr a -> IO b) -> IO b
  41
  42   -- destruction
  43   --
  44   destructArray,  -- :: Storable a =>         Int -> Ptr a -> IO ()
  45   destructArray0, -- :: (Storable a, Eq a) => a   -> Ptr a -> IO ()
  46
  47   -- copying (argument order: destination, source)
  48   --
  49   copyArray,      -- :: Storable a => Ptr a -> Ptr a -> Int -> IO ()
  50   moveArray,      -- :: Storable a => Ptr a -> Ptr a -> Int -> IO ()
  51
  52   -- finding the length
  53   --
  54   lengthArray0,   -- :: (Storable a, Eq a) => a -> Ptr a -> IO Int
  55
  56   -- indexing
  57   --
  58   advancePtr      -- :: Storable a => Ptr a -> Int -> Ptr a
  59 ) where
  60
  61 import Monad
  62
  63 #ifdef __GLASGOW_HASKELL__
  64 import PrelPtr          (Ptr, plusPtr)
  65 import PrelStorable     (Storable(sizeOf,peekElemOff,pokeElemOff,destruct))
  66 import PrelMarshalAlloc (mallocBytes, allocaBytes, reallocBytes)
  67 import PrelMarshalUtils (copyBytes, moveBytes)
  68 import PrelIOBase
  69 import PrelMaybe
  70 import PrelReal         ( fromIntegral )
  71 import PrelNum
  72 import PrelList
  73 import PrelErr
  74 import PrelBase
  75 #endif
  76
  77 -- allocation
  78 -- ----------
  79
  80 -- allocate storage for the given number of elements of a storable type
  81 --
  82 mallocArray :: Storable a => Int -> IO (Ptr a)
  83 mallocArray  = doMalloc undefined
  84   where
  85     doMalloc            :: Storable a => a -> Int -> IO (Ptr a)
  86     doMalloc dummy size  = mallocBytes (size * sizeOf dummy)
  87
  88 -- like `mallocArray', but add an extra element to signal the end of the array
  89 --
  90 mallocArray0      :: Storable a => Int -> IO (Ptr a)
  91 mallocArray0 size  = mallocArray (size + 1)
  92
  93 -- temporarily allocate space for the given number of elements
  94 --
  95 -- * see `MarshalAlloc.alloca' for the storage lifetime constraints
  96 --
  97 allocaArray :: Storable a => Int -> (Ptr a -> IO b) -> IO b
  98 allocaArray  = doAlloca undefined
  99   where
 100     doAlloca            :: Storable a => a -> Int -> (Ptr a -> IO b) -> IO b
 101     doAlloca dummy size  = allocaBytes (size * sizeOf dummy)
 102
 103 -- like `allocaArray', but add an extra element to signal the end of the array
 104 --
 105 allocaArray0      :: Storable a => Int -> (Ptr a -> IO b) -> IO b
 106 allocaArray0 size  = allocaArray (size + 1)
 107
 108 -- adjust the size of an array
 109 --
 110 reallocArray :: Storable a => Ptr a -> Int -> IO (Ptr a)
 111 reallocArray  = doRealloc undefined
 112   where
 113     doRealloc                :: Storable a => a -> Ptr a -> Int -> IO (Ptr a)
 114     doRealloc dummy ptr size  = reallocBytes ptr (size * sizeOf dummy)
 115
 116 -- adjust the size of an array while adding an element for the end marker
 117 --
 118 reallocArray0          :: Storable a => Ptr a -> Int -> IO (Ptr a)
 119 reallocArray0 ptr size  = reallocArray ptr (size + 1)
 120
 121
 122 -- marshalling
 123 -- -----------
 124
 125 -- convert an array of given length into a Haskell list
 126 --
 127 peekArray          :: Storable a => Int -> Ptr a -> IO [a]
 128 peekArray size ptr  = mapM (peekElemOff ptr) [0..size-1]
 129
 130 -- convert an array terminated by the given end marker into a Haskell list
 131 --
 132 peekArray0            :: (Storable a, Eq a) => a -> Ptr a -> IO [a]
 133 peekArray0 marker ptr  = loop 0
 134   where
 135     loop i = do
 136         val <- peekElemOff ptr i
 137         if val == marker then return [] else do
 138             rest <- loop (i+1)
 139             return (val:rest)
 140
 141 -- write the list elements consecutive into memory
 142 --
 143 pokeArray          :: Storable a => Ptr a -> [a] -> IO ()
 144 pokeArray ptr vals  = zipWithM_ (pokeElemOff ptr) [0..] vals
 145
 146 -- write the list elements consecutive into memory and terminate them with the
 147 -- given marker element
 148 --
 149 pokeArray0                 :: Storable a => a -> Ptr a -> [a] -> IO ()
 150 pokeArray0 marker ptr vals  = do
 151   pokeArray ptr vals
 152   pokeElemOff ptr (length vals) marker
 153
 154
 155 -- combined allocation and marshalling
 156 -- -----------------------------------
 157
 158 -- write a list of storable elements into a newly allocated, consecutive
 159 -- sequence of storable values
 160 --
 161 newArray      :: Storable a => [a] -> IO (Ptr a)
 162 newArray vals  = do
 163   ptr <- mallocArray (length vals)
 164   pokeArray ptr vals
 165   return ptr
 166
 167 -- write a list of storable elements into a newly allocated, consecutive
 168 -- sequence of storable values, where the end is fixed by the given end marker
 169 --
 170 newArray0             :: Storable a => a -> [a] -> IO (Ptr a)
 171 newArray0 marker vals  = do
 172   ptr <- mallocArray0 (length vals)
 173   pokeArray0 marker ptr vals
 174   return ptr
 175
 176 -- temporarily store a list of storable values in memory
 177 --
 178 withArray        :: Storable a => [a] -> (Ptr a -> IO b) -> IO b
 179 withArray vals f  =
 180   allocaArray len $ \ptr -> do
 181       pokeArray ptr vals
 182       res <- f ptr
 183       destructArray len ptr
 184       return res
 185   where
 186     len = length vals
 187
 188 -- like `withArray', but a terminator indicates where the array ends
 189 --
 190 withArray0               :: Storable a => a -> [a] -> (Ptr a -> IO b) -> IO b
 191 withArray0 marker vals f  =
 192   allocaArray0 len $ \ptr -> do
 193       pokeArray0 marker ptr vals
 194       res <- f ptr
 195       destructArray (len+1) ptr
 196       return res
 197   where
 198     len = length vals
 199
 200
 201 -- destruction
 202 -- -----------
 203
 204 -- destruct each element of an array (in reverse order)
 205 --
 206 destructArray          :: Storable a => Int -> Ptr a -> IO ()
 207 destructArray size ptr  =
 208   sequence_ [destruct (ptr `advancePtr` i)
 209     | i <- [size-1, size-2 .. 0]]
 210
 211 -- like `destructArray', but a terminator indicates where the array ends
 212 --
 213 destructArray0            :: (Storable a, Eq a) => a -> Ptr a -> IO ()
 214 destructArray0 marker ptr  = do
 215   size <- lengthArray0 marker ptr
 216   sequence_ [destruct (ptr `advancePtr` i)
 217     | i <- [size, size-1 .. 0]]
 218
 219
 220 -- copying (argument order: destination, source)
 221 -- -------
 222
 223 -- copy the given number of elements from the second array (source) into the
 224 -- first array (destination); the copied areas may *not* overlap
 225 --
 226 copyArray :: Storable a => Ptr a -> Ptr a -> Int -> IO ()
 227 copyArray  = doCopy undefined
 228   where
 229     doCopy                     :: Storable a => a -> Ptr a -> Ptr a -> Int -> IO ()
 230     doCopy dummy dest src size  = copyBytes dest src (size * sizeOf dummy)
 231
 232 -- copy the given number of elements from the second array (source) into the
 233 -- first array (destination); the copied areas *may* overlap
 234 --
 235 moveArray :: Storable a => Ptr a -> Ptr a -> Int -> IO ()
 236 moveArray  = doMove undefined
 237   where
 238     doMove                     :: Storable a => a -> Ptr a -> Ptr a -> Int -> IO ()
 239     doMove dummy dest src size  = moveBytes dest src (size * sizeOf dummy)
 240
 241
 242 -- finding the length
 243 -- ------------------
 244
 245 -- return the number of elements in an array, excluding the terminator
 246 --
 247 lengthArray0            :: (Storable a, Eq a) => a -> Ptr a -> IO Int
 248 lengthArray0 marker ptr  = loop 0
 249   where
 250     loop i = do
 251         val <- peekElemOff ptr i
 252         if val == marker then return i else loop (i+1)
 253
 254
 255 -- indexing
 256 -- --------
 257
 258 -- advance a pointer into an array by the given number of elements
 259 --
 260 advancePtr :: Storable a => Ptr a -> Int -> Ptr a
 261 advancePtr  = doAdvance undefined
 262   where
 263     doAdvance             :: Storable a => a -> Ptr a -> Int -> Ptr a
 264     doAdvance dummy ptr i  = ptr `plusPtr` (i * sizeOf dummy)
 265
 266 \end{code}