Foreign/Marshal/Utils.hs

   1 {-# OPTIONS -fno-implicit-prelude #-}
   2 -----------------------------------------------------------------------------
   3 -- |
   4 -- Module      :  Foreign.Marshal.Utils
   5 -- Copyright   :  (c) The FFI task force 2001
   6 -- License     :  BSD-style (see the file libraries/core/LICENSE)
   7 --
   8 -- Maintainer  :  ffi@haskell.org
   9 -- Stability   :  provisional
  10 -- Portability :  portable
  11 --
  12 -- $Id: Utils.hs,v 1.4 2002/04/24 16:31:44 simonmar Exp $
  13 --
  14 -- Utilities for primitive marshaling
  15 --
  16 -----------------------------------------------------------------------------
  17
  18 module Foreign.Marshal.Utils (
  19
  20   -- combined allocation and marshalling
  21   --
  22   withObject,    -- :: Storable a => a -> (Ptr a -> IO b) -> IO b
  23   {- FIXME: should be `with' -}
  24   new,           -- :: Storable a => a -> IO (Ptr a)
  25
  26   -- marshalling of Boolean values (non-zero corresponds to `True')
  27   --
  28   fromBool,      -- :: Num a => Bool -> a
  29   toBool,        -- :: Num a => a -> Bool
  30
  31   -- marshalling of Maybe values
  32   --
  33   maybeNew,      -- :: (      a -> IO (Ptr a))
  34                  -- -> (Maybe a -> IO (Ptr a))
  35   maybeWith,     -- :: (      a -> (Ptr b -> IO c) -> IO c)
  36                  -- -> (Maybe a -> (Ptr b -> IO c) -> IO c)
  37   maybePeek,     -- :: (Ptr a -> IO        b )
  38                  -- -> (Ptr a -> IO (Maybe b))
  39
  40   -- marshalling lists of storable objects
  41   --
  42   withMany,      -- :: (a -> (b -> res) -> res) -> [a] -> ([b] -> res) -> res
  43
  44   -- Haskellish interface to memcpy and memmove
  45   -- (argument order: destination, source)
  46   --
  47   copyBytes,     -- :: Ptr a -> Ptr a -> Int -> IO ()
  48   moveBytes      -- :: Ptr a -> Ptr a -> Int -> IO ()
  49 ) where
  50
  51 import Data.Maybe
  52
  53 #ifdef __GLASGOW_HASKELL__
  54 import Foreign.Ptr              ( Ptr, nullPtr )
  55 import GHC.Storable             ( Storable(poke) )
  56 import Foreign.C.TypesISO       ( CSize )
  57 import Foreign.Marshal.Alloc    ( malloc, alloca )
  58 import GHC.IOBase
  59 import GHC.Real                 ( fromIntegral )
  60 import GHC.Num
  61 import GHC.Base
  62 #endif
  63
  64 -- combined allocation and marshalling
  65 -- -----------------------------------
  66
  67 -- allocate storage for a value and marshal it into this storage
  68 --
  69 new     :: Storable a => a -> IO (Ptr a)
  70 new val  =
  71   do
  72     ptr <- malloc
  73     poke ptr val
  74     return ptr
  75
  76 -- allocate temporary storage for a value and marshal it into this storage
  77 --
  78 -- * see the life time constraints imposed by `alloca'
  79 --
  80 {- FIXME: should be called `with' -}
  81 withObject       :: Storable a => a -> (Ptr a -> IO b) -> IO b
  82 withObject val f  =
  83   alloca $ \ptr -> do
  84     poke ptr val
  85     res <- f ptr
  86     return res
  87
  88
  89 -- marshalling of Boolean values (non-zero corresponds to `True')
  90 -- -----------------------------
  91
  92 -- convert a Haskell Boolean to its numeric representation
  93 --
  94 fromBool       :: Num a => Bool -> a
  95 fromBool False  = 0
  96 fromBool True   = 1
  97
  98 -- convert a Boolean in numeric representation to a Haskell value
  99 --
 100 toBool :: Num a => a -> Bool
 101 toBool  = (/= 0)
 102
 103
 104 -- marshalling of Maybe values
 105 -- ---------------------------
 106
 107 -- allocate storage and marshall a storable value wrapped into a `Maybe'
 108 --
 109 -- * the `nullPtr' is used to represent `Nothing'
 110 --
 111 maybeNew :: (      a -> IO (Ptr a))
 112          -> (Maybe a -> IO (Ptr a))
 113 maybeNew  = maybe (return nullPtr)
 114
 115 -- converts a withXXX combinator into one marshalling a value wrapped into a
 116 -- `Maybe'
 117 --
 118 maybeWith :: (      a -> (Ptr b -> IO c) -> IO c)
 119           -> (Maybe a -> (Ptr b -> IO c) -> IO c)
 120 maybeWith  = maybe ($ nullPtr)
 121
 122 -- convert a peek combinator into a one returning `Nothing' if applied to a
 123 -- `nullPtr'
 124 --
 125 maybePeek                           :: (Ptr a -> IO b) -> Ptr a -> IO (Maybe b)
 126 maybePeek peek ptr | ptr == nullPtr  = return Nothing
 127                    | otherwise       = do a <- peek ptr; return (Just a)
 128
 129
 130 -- marshalling lists of storable objects
 131 -- -------------------------------------
 132
 133 -- replicates a withXXX combinator over a list of objects, yielding a list of
 134 -- marshalled objects
 135 --
 136 withMany :: (a -> (b -> res) -> res)  -- withXXX combinator for one object
 137          -> [a]                       -- storable objects
 138          -> ([b] -> res)              -- action on list of marshalled obj.s
 139          -> res
 140 withMany _       []     f = f []
 141 withMany withFoo (x:xs) f = withFoo x $ \x' ->
 142                               withMany withFoo xs (\xs' -> f (x':xs'))
 143
 144
 145 -- Haskellish interface to memcpy and memmove
 146 -- ------------------------------------------
 147
 148 -- copies the given number of bytes from the second area (source) into the
 149 -- first (destination); the copied areas may *not* overlap
 150 --
 151 copyBytes               :: Ptr a -> Ptr a -> Int -> IO ()
 152 copyBytes dest src size  = memcpy dest src (fromIntegral size)
 153
 154 -- copies the given number of elements from the second area (source) into the
 155 -- first (destination); the copied areas *may* overlap
 156 --
 157 moveBytes               :: Ptr a -> Ptr a -> Int -> IO ()
 158 moveBytes dest src size  = memmove dest src (fromIntegral size)
 159
 160
 161 -- auxilliary routines
 162 -- -------------------
 163
 164 -- basic C routines needed for memory copying
 165 --
 166 foreign import ccall unsafe memcpy  :: Ptr a -> Ptr a -> CSize -> IO ()
 167 foreign import ccall unsafe memmove :: Ptr a -> Ptr a -> CSize -> IO ()