[project @ 2005-02-02 15:20:11 by simonmar]

[ghc-base.git] / Foreign / Marshal / Utils.hs

diff --git a/Foreign/Marshal/Utils.hs b/Foreign/Marshal/Utils.hs
index 87881b6..b62e618 100644 (file)
--- a/Foreign/Marshal/Utils.hs
+++ b/Foreign/Marshal/Utils.hs
@@ -1,9 +1,9 @@
-{-# OPTIONS -fno-implicit-prelude #-}
+{-# OPTIONS_GHC -fno-implicit-prelude #-}
 -----------------------------------------------------------------------------
 -- |
 -- Module      :  Foreign.Marshal.Utils
 -- Copyright   :  (c) The FFI task force 2001
--- License     :  BSD-style (see the file libraries/core/LICENSE)
+-- License     :  BSD-style (see the file libraries/base/LICENSE)
 -- 
 -- Maintainer  :  ffi@haskell.org
 -- Stability   :  provisional
@@ -18,8 +18,7 @@ module Foreign.Marshal.Utils (
 
   -- ** Combined allocation and marshalling
   --
-  withObject,    -- :: Storable a => a -> (Ptr a -> IO b) -> IO b
-  {- FIXME: should be `with' -}
+  with,          -- :: Storable a => a -> (Ptr a -> IO b) -> IO b
   new,           -- :: Storable a => a -> IO (Ptr a)
 
   -- ** Marshalling of Boolean values (non-zero corresponds to 'True')
@@ -41,29 +40,43 @@ module Foreign.Marshal.Utils (
   withMany,      -- :: (a -> (b -> res) -> res) -> [a] -> ([b] -> res) -> res
 
   -- ** Haskellish interface to memcpy and memmove
-
   -- | (argument order: destination, source)
+  --
   copyBytes,     -- :: Ptr a -> Ptr a -> Int -> IO ()
-  moveBytes      -- :: Ptr a -> Ptr a -> Int -> IO ()
+  moveBytes,     -- :: Ptr a -> Ptr a -> Int -> IO ()
+
+  -- ** DEPRECATED FUNCTIONS (don\'t use; they may disappear at any time)
+  --
+  withObject     -- :: Storable a => a -> (Ptr a -> IO b) -> IO b
 ) where
 
 import Data.Maybe
-
-#ifdef __GLASGOW_HASKELL__
 import Foreign.Ptr             ( Ptr, nullPtr )
-import GHC.Storable            ( Storable(poke) )
-import Foreign.C.TypesISO      ( CSize )
+import Foreign.Storable                ( Storable(poke) )
+import Foreign.C.Types         ( CSize )
 import Foreign.Marshal.Alloc   ( malloc, alloca )
+
+#ifdef __GLASGOW_HASKELL__
 import GHC.IOBase
 import GHC.Real                        ( fromIntegral )
 import GHC.Num
 import GHC.Base
 #endif
 
+#ifdef __NHC__
+import Foreign.C.Types         ( CInt(..) )
+#endif
+
 -- combined allocation and marshalling
 -- -----------------------------------
 
--- |Allocate storage for a value and marshal it into this storage
+-- |Allocate a block of memory and marshal a value into it
+-- (the combination of 'malloc' and 'poke').
+-- The size of the area allocated is determined by the 'Foreign.Storable.sizeOf'
+-- method from the instance of 'Storable' for the appropriate type.
+--
+-- The memory may be deallocated using 'Foreign.Marshal.Alloc.free' or
+-- 'Foreign.Marshal.Alloc.finalizerFree' when no longer required.
 --
 new     :: Storable a => a -> IO (Ptr a)
 new val  = 
@@ -72,18 +85,26 @@ new val  =
     poke ptr val
     return ptr
 
--- |Allocate temporary storage for a value and marshal it into this storage
+-- |@'with' val f@ executes the computation @f@, passing as argument
+-- a pointer to a temporarily allocated block of memory into which
+-- @val@ has been marshalled (the combination of 'alloca' and 'poke').
 --
--- * see the life time constraints imposed by 'alloca'
+-- The memory is freed when @f@ terminates (either normally or via an
+-- exception), so the pointer passed to @f@ must /not/ be used after this.
 --
-{- FIXME: should be called `with' -}
-withObject       :: Storable a => a -> (Ptr a -> IO b) -> IO b
-withObject val f  =
+with       :: Storable a => a -> (Ptr a -> IO b) -> IO b
+with val f  =
   alloca $ \ptr -> do
     poke ptr val
     res <- f ptr
     return res
 
+-- old DEPRECATED name (don't use; may disappear at any time)
+--
+withObject :: Storable a => a -> (Ptr a -> IO b) -> IO b
+{-# DEPRECATED withObject "use `with' instead" #-}
+withObject  = with
+
 
 -- marshalling of Boolean values (non-zero corresponds to 'True')
 -- -----------------------------
@@ -111,8 +132,8 @@ maybeNew :: (      a -> IO (Ptr a))
         -> (Maybe a -> IO (Ptr a))
 maybeNew  = maybe (return nullPtr)
 
--- |Converts a @withXXX@ combinator into one marshalling a value wrapped into a
--- 'Maybe'
+-- |Converts a @withXXX@ combinator into one marshalling a value wrapped
+-- into a 'Maybe', using 'nullPtr' to represent 'Nothing'.
 --
 maybeWith :: (      a -> (Ptr b -> IO c) -> IO c) 
          -> (Maybe a -> (Ptr b -> IO c) -> IO c)
@@ -162,5 +183,5 @@ moveBytes dest src size  = memmove dest src (fromIntegral size)
 
 -- |Basic C routines needed for memory copying
 --
-foreign import ccall unsafe memcpy  :: Ptr a -> Ptr a -> CSize -> IO ()
-foreign import ccall unsafe memmove :: Ptr a -> Ptr a -> CSize -> IO ()
+foreign import ccall unsafe "string.h" memcpy  :: Ptr a -> Ptr a -> CSize -> IO ()
+foreign import ccall unsafe "string.h" memmove :: Ptr a -> Ptr a -> CSize -> IO ()