[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 08bee23..b62e618 100644 (file)
--- a/Foreign/Marshal/Utils.hs
+++ b/Foreign/Marshal/Utils.hs
@@ -1,4 +1,4 @@
-{-# OPTIONS -fno-implicit-prelude #-}
+{-# OPTIONS_GHC -fno-implicit-prelude #-}
 -----------------------------------------------------------------------------
 -- |
 -- Module      :  Foreign.Marshal.Utils
@@ -51,22 +51,32 @@ module Foreign.Marshal.Utils (
 ) 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  = 
@@ -75,9 +85,12 @@ 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.
 --
 with       :: Storable a => a -> (Ptr a -> IO b) -> IO b
 with val f  =
@@ -119,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)
@@ -170,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 ()