Remove Control.Parallel*, now in package parallel

[haskell-directory.git] / Foreign / Marshal / Utils.hs

diff --git a/Foreign/Marshal/Utils.hs b/Foreign/Marshal/Utils.hs
index c88fb51..72f7d9b 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
@@ -44,10 +44,6 @@ module Foreign.Marshal.Utils (
   --
   copyBytes,     -- :: 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
@@ -64,13 +60,19 @@ import GHC.Base
 #endif
 
 #ifdef __NHC__
-import NHC.FFI                 ( CInt(..) )
+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  = 
@@ -79,9 +81,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  =
@@ -90,12 +95,6 @@ with val f  =
     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')
 -- -----------------------------
@@ -123,8 +122,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)
@@ -160,13 +159,15 @@ withMany withFoo (x:xs) f = withFoo x $ \x' ->
 -- first (destination); the copied areas may /not/ overlap
 --
 copyBytes               :: Ptr a -> Ptr a -> Int -> IO ()
-copyBytes dest src size  = memcpy dest src (fromIntegral size)
+copyBytes dest src size  = do memcpy dest src (fromIntegral size)
+                              return ()
 
--- |Copies the given number of elements from the second area (source) into the
+-- |Copies the given number of bytes from the second area (source) into the
 -- first (destination); the copied areas /may/ overlap
 --
 moveBytes               :: Ptr a -> Ptr a -> Int -> IO ()
-moveBytes dest src size  = memmove dest src (fromIntegral size)
+moveBytes dest src size  = do memmove dest src (fromIntegral size)
+                              return ()
 
 
 -- auxilliary routines
@@ -174,5 +175,5 @@ moveBytes dest src size  = memmove dest src (fromIntegral size)
 
 -- |Basic C routines needed for memory copying
 --
-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 ()
+foreign import ccall unsafe "string.h" memcpy  :: Ptr a -> Ptr a -> CSize -> IO (Ptr a)
+foreign import ccall unsafe "string.h" memmove :: Ptr a -> Ptr a -> CSize -> IO (Ptr a)