ghc/lib/std/PrelMarshalArray.lhs

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