The IO type has moved to GHC.Types in ghc-prim
[ghc.git] / libraries / base / Foreign / Marshal / Utils.hs
1 {-# OPTIONS_GHC -XNoImplicitPrelude #-}
2 -----------------------------------------------------------------------------
3 -- |
4 -- Module : Foreign.Marshal.Utils
5 -- Copyright : (c) The FFI task force 2001
6 -- License : BSD-style (see the file libraries/base/LICENSE)
7 --
8 -- Maintainer : ffi@haskell.org
9 -- Stability : provisional
10 -- Portability : portable
11 --
12 -- Utilities for primitive marshaling
13 --
14 -----------------------------------------------------------------------------
15
16 module Foreign.Marshal.Utils (
17 -- * General marshalling utilities
18
19 -- ** Combined allocation and marshalling
20 --
21 with, -- :: Storable a => a -> (Ptr a -> IO b) -> IO b
22 new, -- :: Storable a => a -> IO (Ptr a)
23
24 -- ** Marshalling of Boolean values (non-zero corresponds to 'True')
25 --
26 fromBool, -- :: Num a => Bool -> a
27 toBool, -- :: Num a => a -> Bool
28
29 -- ** Marshalling of Maybe values
30 --
31 maybeNew, -- :: ( a -> IO (Ptr a))
32 -- -> (Maybe a -> IO (Ptr a))
33 maybeWith, -- :: ( a -> (Ptr b -> IO c) -> IO c)
34 -- -> (Maybe a -> (Ptr b -> IO c) -> IO c)
35 maybePeek, -- :: (Ptr a -> IO b )
36 -- -> (Ptr a -> IO (Maybe b))
37
38 -- ** Marshalling lists of storable objects
39 --
40 withMany, -- :: (a -> (b -> res) -> res) -> [a] -> ([b] -> res) -> res
41
42 -- ** Haskellish interface to memcpy and memmove
43 -- | (argument order: destination, source)
44 --
45 copyBytes, -- :: Ptr a -> Ptr a -> Int -> IO ()
46 moveBytes, -- :: Ptr a -> Ptr a -> Int -> IO ()
47 ) where
48
49 import Data.Maybe
50 import Foreign.Ptr ( Ptr, nullPtr )
51 import Foreign.Storable ( Storable(poke) )
52 import Foreign.C.Types ( CSize )
53 import Foreign.Marshal.Alloc ( malloc, alloca )
54
55 #ifdef __GLASGOW_HASKELL__
56 import GHC.Real ( fromIntegral )
57 import GHC.Num
58 import GHC.Base
59 #endif
60
61 #ifdef __NHC__
62 import Foreign.C.Types ( CInt(..) )
63 #endif
64
65 -- combined allocation and marshalling
66 -- -----------------------------------
67
68 -- |Allocate a block of memory and marshal a value into it
69 -- (the combination of 'malloc' and 'poke').
70 -- The size of the area allocated is determined by the 'Foreign.Storable.sizeOf'
71 -- method from the instance of 'Storable' for the appropriate type.
72 --
73 -- The memory may be deallocated using 'Foreign.Marshal.Alloc.free' or
74 -- 'Foreign.Marshal.Alloc.finalizerFree' when no longer required.
75 --
76 new :: Storable a => a -> IO (Ptr a)
77 new val =
78 do
79 ptr <- malloc
80 poke ptr val
81 return ptr
82
83 -- |@'with' val f@ executes the computation @f@, passing as argument
84 -- a pointer to a temporarily allocated block of memory into which
85 -- @val@ has been marshalled (the combination of 'alloca' and 'poke').
86 --
87 -- The memory is freed when @f@ terminates (either normally or via an
88 -- exception), so the pointer passed to @f@ must /not/ be used after this.
89 --
90 with :: Storable a => a -> (Ptr a -> IO b) -> IO b
91 with val f =
92 alloca $ \ptr -> do
93 poke ptr val
94 res <- f ptr
95 return res
96
97
98 -- marshalling of Boolean values (non-zero corresponds to 'True')
99 -- -----------------------------
100
101 -- |Convert a Haskell 'Bool' to its numeric representation
102 --
103 fromBool :: Num a => Bool -> a
104 fromBool False = 0
105 fromBool True = 1
106
107 -- |Convert a Boolean in numeric representation to a Haskell value
108 --
109 toBool :: Num a => a -> Bool
110 toBool = (/= 0)
111
112
113 -- marshalling of Maybe values
114 -- ---------------------------
115
116 -- |Allocate storage and marshall a storable value wrapped into a 'Maybe'
117 --
118 -- * the 'nullPtr' is used to represent 'Nothing'
119 --
120 maybeNew :: ( a -> IO (Ptr a))
121 -> (Maybe a -> IO (Ptr a))
122 maybeNew = maybe (return nullPtr)
123
124 -- |Converts a @withXXX@ combinator into one marshalling a value wrapped
125 -- into a 'Maybe', using 'nullPtr' to represent 'Nothing'.
126 --
127 maybeWith :: ( a -> (Ptr b -> IO c) -> IO c)
128 -> (Maybe a -> (Ptr b -> IO c) -> IO c)
129 maybeWith = maybe ($ nullPtr)
130
131 -- |Convert a peek combinator into a one returning 'Nothing' if applied to a
132 -- 'nullPtr'
133 --
134 maybePeek :: (Ptr a -> IO b) -> Ptr a -> IO (Maybe b)
135 maybePeek peek ptr | ptr == nullPtr = return Nothing
136 | otherwise = do a <- peek ptr; return (Just a)
137
138
139 -- marshalling lists of storable objects
140 -- -------------------------------------
141
142 -- |Replicates a @withXXX@ combinator over a list of objects, yielding a list of
143 -- marshalled objects
144 --
145 withMany :: (a -> (b -> res) -> res) -- withXXX combinator for one object
146 -> [a] -- storable objects
147 -> ([b] -> res) -- action on list of marshalled obj.s
148 -> res
149 withMany _ [] f = f []
150 withMany withFoo (x:xs) f = withFoo x $ \x' ->
151 withMany withFoo xs (\xs' -> f (x':xs'))
152
153
154 -- Haskellish interface to memcpy and memmove
155 -- ------------------------------------------
156
157 -- |Copies the given number of bytes from the second area (source) into the
158 -- first (destination); the copied areas may /not/ overlap
159 --
160 copyBytes :: Ptr a -> Ptr a -> Int -> IO ()
161 copyBytes dest src size = do memcpy dest src (fromIntegral size)
162 return ()
163
164 -- |Copies the given number of bytes from the second area (source) into the
165 -- first (destination); the copied areas /may/ overlap
166 --
167 moveBytes :: Ptr a -> Ptr a -> Int -> IO ()
168 moveBytes dest src size = do memmove dest src (fromIntegral size)
169 return ()
170
171
172 -- auxilliary routines
173 -- -------------------
174
175 -- |Basic C routines needed for memory copying
176 --
177 foreign import ccall unsafe "string.h" memcpy :: Ptr a -> Ptr a -> CSize -> IO (Ptr a)
178 foreign import ccall unsafe "string.h" memmove :: Ptr a -> Ptr a -> CSize -> IO (Ptr a)