ghc/lib/std/PrelMarshalArray.lhs

   1 % -----------------------------------------------------------------------------
   2 % $Id: PrelMarshalArray.lhs,v 1.1 2001/01/11 17:25:57 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 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   -- copying (argument order: destination, source)
  41   --
  42   copyArray,     -- :: Storable a => Ptr a -> Ptr a -> Int -> IO ()
  43   moveArray,     -- :: Storable a => Ptr a -> Ptr a -> Int -> IO ()
  44
  45   -- indexing
  46   --
  47   advancePtr     -- :: Storable a => Ptr a -> Int -> Ptr a
  48 ) where
  49
  50 import Monad        (zipWithM_)
  51
  52 import PrelPtr          (Ptr, plusPtr)
  53 import PrelStorable     (Storable(sizeOf, peekElemOff, pokeElemOff))
  54 import PrelMarshalAlloc (mallocBytes, allocaBytes, reallocBytes)
  55 import PrelMarshalUtils (copyBytes, moveBytes)
  56
  57
  58 -- allocation
  59 -- ----------
  60
  61 -- allocate storage for the given number of elements of a storable type
  62 --
  63 mallocArray :: Storable a => Int -> IO (Ptr a)
  64 mallocArray  = doMalloc undefined
  65   where
  66     doMalloc            :: Storable a => a -> Int -> IO (Ptr a)
  67     doMalloc dummy size  = mallocBytes (size * sizeOf dummy)
  68
  69 -- like `mallocArray', but add an extra element to signal the end of the array
  70 --
  71 mallocArray0      :: Storable a => Int -> IO (Ptr a)
  72 mallocArray0 size  = mallocArray (size + 1)
  73
  74 -- temporarily allocate space for the given number of elements
  75 --
  76 -- * see `MarshalAlloc.alloca' for the storage lifetime constraints
  77 --
  78 allocaArray :: Storable a => Int -> (Ptr a -> IO b) -> IO b
  79 allocaArray  = doAlloca undefined
  80   where
  81     doAlloca            :: Storable a => a -> Int -> (Ptr a -> IO b) -> IO b
  82     doAlloca dummy size  = allocaBytes (size * sizeOf dummy)
  83
  84 -- like `allocaArray', but add an extra element to signal the end of the array
  85 --
  86 allocaArray0      :: Storable a => Int -> (Ptr a -> IO b) -> IO b
  87 allocaArray0 size  = allocaArray (size + 1)
  88
  89 -- adjust the size of an array
  90 --
  91 reallocArray :: Storable a => Ptr a -> Int -> IO (Ptr a)
  92 reallocArray  = doRealloc undefined
  93   where
  94     doRealloc                :: Storable a => a -> Ptr a -> Int -> IO (Ptr a)
  95     doRealloc dummy ptr size  = reallocBytes ptr (size * sizeOf dummy)
  96
  97 -- adjust the size of an array while adding an element for the end marker
  98 --
  99 reallocArray0          :: Storable a => Ptr a -> Int -> IO (Ptr a)
 100 reallocArray0 ptr size  = reallocArray ptr (size + 1)
 101
 102
 103 -- marshalling
 104 -- -----------
 105
 106 -- convert an array of given length into a Haskell list
 107 --
 108 peekArray          :: Storable a => Int -> Ptr a -> IO [a]
 109 peekArray size ptr  = mapM (peekElemOff ptr) [0..size-1]
 110
 111 -- convert an array terminated by the given end marker into a Haskell list
 112 --
 113 peekArray0            :: (Storable a, Eq a) => a -> Ptr a -> IO [a]
 114 peekArray0 marker ptr  = loop 0
 115   where
 116     loop i = do
 117         val <- peekElemOff ptr i
 118         if val == marker then return [] else do
 119             rest <- loop (i+1)
 120             return (val:rest)
 121
 122 -- write the list elements consecutive into memory
 123 --
 124 pokeArray          :: Storable a => Ptr a -> [a] -> IO ()
 125 pokeArray ptr vals  = zipWithM_ (pokeElemOff ptr) [0..] vals
 126
 127 -- write the list elements consecutive into memory and terminate them with the
 128 -- given marker element
 129 --
 130 pokeArray0                 :: Storable a => a -> Ptr a -> [a] -> IO ()
 131 pokeArray0 marker ptr vals  = do
 132   pokeArray ptr vals
 133   pokeElemOff ptr (length vals) marker
 134
 135
 136 -- combined allocation and marshalling
 137 -- -----------------------------------
 138
 139 -- write a list of storable elements into a newly allocated, consecutive
 140 -- sequence of storable values
 141 --
 142 newArray      :: Storable a => [a] -> IO (Ptr a)
 143 newArray vals  = do
 144   ptr <- mallocArray (length vals)
 145   pokeArray ptr vals
 146   return ptr
 147
 148 -- write a list of storable elements into a newly allocated, consecutive
 149 -- sequence of storable values, where the end is fixed by the given end maker
 150 --
 151 newArray0             :: Storable a => a -> [a] -> IO (Ptr a)
 152 newArray0 marker vals  = do
 153   ptr <- mallocArray0 (length vals)
 154   pokeArray0 marker ptr vals
 155   return ptr
 156
 157 -- temporarily store a list of storable values in memory
 158 --
 159 withArray        :: Storable a => [a] -> (Ptr a -> IO b) -> IO b
 160 withArray vals f  = allocaArray (length vals) $ \ptr -> do
 161   pokeArray ptr vals
 162   f ptr
 163
 164 -- `like withArray', but a terminator indicates where the array ends
 165 --
 166 withArray0               :: Storable a => a -> [a] -> (Ptr a -> IO b) -> IO b
 167 withArray0 marker vals f  = allocaArray0 (length vals) $ \ptr -> do
 168   pokeArray0 marker ptr vals
 169   f ptr
 170
 171
 172 -- copying
 173 -- -------
 174
 175 -- copies the given number of elements from the second array (source) into the
 176 -- first array (destination); the copied areas may *not* overlap
 177 --
 178 copyArray :: Storable a => Ptr a -> Ptr a -> Int -> IO ()
 179 copyArray  = doCopy undefined
 180   where
 181     doCopy                     :: Storable a => a -> Ptr a -> Ptr a -> Int -> IO ()
 182     doCopy dummy dest src size  = copyBytes dest src (size * sizeOf dummy)
 183
 184 -- copies the given number of elements from the second array (source) into the
 185 -- first array (destination); the copied areas *may* overlap
 186 --
 187 moveArray :: Storable a => Ptr a -> Ptr a -> Int -> IO ()
 188 moveArray  = doMove undefined
 189   where
 190     doMove                     :: Storable a => a -> Ptr a -> Ptr a -> Int -> IO ()
 191     doMove dummy dest src size  = moveBytes dest src (size * sizeOf dummy)
 192
 193
 194 -- indexing
 195 -- --------
 196
 197 -- advance a pointer into an array by the given number of elements
 198 --
 199 advancePtr :: Storable a => Ptr a -> Int -> Ptr a
 200 advancePtr  = doAdvance undefined
 201   where
 202     doAdvance             :: Storable a => a -> Ptr a -> Int -> Ptr a
 203     doAdvance dummy ptr i  = ptr `plusPtr` (i * sizeOf dummy)
 204
 205 \end{code}