X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;ds=sidebyside;f=Foreign%2FMarshal%2FUtils.hs;h=06528b2b4ec1cc0d89ca9bd584720cdfad913217;hb=dce1f7d375ddf22fc17ef98734a8ee6e302b1a45;hp=5b21ca04e1696349a94ab7045e88f0fc541b8c70;hpb=9fa9bc17072a58c0bae2cce4764d38677e96ac29;p=ghc-base.git diff --git a/Foreign/Marshal/Utils.hs b/Foreign/Marshal/Utils.hs index 5b21ca0..06528b2 100644 --- a/Foreign/Marshal/Utils.hs +++ b/Foreign/Marshal/Utils.hs @@ -3,32 +3,30 @@ -- | -- 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 -- Portability : portable -- --- $Id: Utils.hs,v 1.4 2002/04/24 16:31:44 simonmar Exp $ --- -- Utilities for primitive marshaling -- ----------------------------------------------------------------------------- module Foreign.Marshal.Utils ( + -- * General marshalling utilities - -- combined allocation and marshalling + -- ** 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') + -- ** Marshalling of Boolean values (non-zero corresponds to 'True') -- fromBool, -- :: Num a => Bool -> a toBool, -- :: Num a => a -> Bool - -- marshalling of Maybe values + -- ** Marshalling of Maybe values -- maybeNew, -- :: ( a -> IO (Ptr a)) -- -> (Maybe a -> IO (Ptr a)) @@ -37,24 +35,28 @@ module Foreign.Marshal.Utils ( maybePeek, -- :: (Ptr a -> IO b ) -- -> (Ptr a -> IO (Maybe b)) - -- marshalling lists of storable objects + -- ** Marshalling lists of storable objects -- withMany, -- :: (a -> (b -> res) -> res) -> [a] -> ([b] -> res) -> res - -- Haskellish interface to memcpy and memmove - -- (argument order: destination, source) + -- ** 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, CInt(..) ) import Foreign.Marshal.Alloc ( malloc, alloca ) + +#ifdef __GLASGOW_HASKELL__ import GHC.IOBase import GHC.Real ( fromIntegral ) import GHC.Num @@ -64,7 +66,7 @@ import GHC.Base -- combined allocation and marshalling -- ----------------------------------- --- allocate storage for a value and marshal it into this storage +-- |Allocate storage for a value and marshal it into this storage -- new :: Storable a => a -> IO (Ptr a) new val = @@ -73,29 +75,34 @@ new val = poke ptr val return ptr --- allocate temporary storage for a value and marshal it into this storage +-- |Allocate temporary storage for a value and marshal it into this storage -- --- * see the life time constraints imposed by `alloca' +-- * see the life time constraints imposed by 'alloca' -- -{- 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') +-- marshalling of Boolean values (non-zero corresponds to 'True') -- ----------------------------- --- convert a Haskell Boolean to its numeric representation +-- |Convert a Haskell 'Bool' to its numeric representation -- fromBool :: Num a => Bool -> a fromBool False = 0 fromBool True = 1 --- convert a Boolean in numeric representation to a Haskell value +-- |Convert a Boolean in numeric representation to a Haskell value -- toBool :: Num a => a -> Bool toBool = (/= 0) @@ -104,23 +111,23 @@ toBool = (/= 0) -- marshalling of Maybe values -- --------------------------- --- allocate storage and marshall a storable value wrapped into a `Maybe' +-- |Allocate storage and marshall a storable value wrapped into a 'Maybe' -- --- * the `nullPtr' is used to represent `Nothing' +-- * the 'nullPtr' is used to represent 'Nothing' -- 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' -- maybeWith :: ( a -> (Ptr b -> IO c) -> IO c) -> (Maybe a -> (Ptr b -> IO c) -> IO c) maybeWith = maybe ($ nullPtr) --- convert a peek combinator into a one returning `Nothing' if applied to a --- `nullPtr' +-- |Convert a peek combinator into a one returning 'Nothing' if applied to a +-- 'nullPtr' -- maybePeek :: (Ptr a -> IO b) -> Ptr a -> IO (Maybe b) maybePeek peek ptr | ptr == nullPtr = return Nothing @@ -130,7 +137,7 @@ maybePeek peek ptr | ptr == nullPtr = return Nothing -- marshalling lists of storable objects -- ------------------------------------- --- replicates a withXXX combinator over a list of objects, yielding a list of +-- |Replicates a @withXXX@ combinator over a list of objects, yielding a list of -- marshalled objects -- withMany :: (a -> (b -> res) -> res) -- withXXX combinator for one object @@ -145,14 +152,14 @@ withMany withFoo (x:xs) f = withFoo x $ \x' -> -- Haskellish interface to memcpy and memmove -- ------------------------------------------ --- copies the given number of bytes from the second area (source) into the --- first (destination); the copied areas may *not* overlap +-- |Copies the given number of bytes from the second area (source) into the +-- first (destination); the copied areas may /not/ overlap -- copyBytes :: Ptr a -> Ptr a -> Int -> IO () copyBytes dest src size = memcpy dest src (fromIntegral size) --- copies the given number of elements from the second area (source) into the --- first (destination); the copied areas *may* overlap +-- |Copies the given number of elements 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) @@ -161,7 +168,7 @@ moveBytes dest src size = memmove dest src (fromIntegral size) -- auxilliary routines -- ------------------- --- basic C routines needed for memory copying +-- |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 ()