1 {-# OPTIONS -fno-implicit-prelude #-}
2 -----------------------------------------------------------------------------
4 -- Module : Foreign.Marshal.Alloc
5 -- Copyright : (c) The FFI task force 2001
6 -- License : BSD-style (see the file libraries/base/LICENSE)
8 -- Maintainer : ffi@haskell.org
9 -- Stability : provisional
10 -- Portability : portable
12 -- Marshalling support: basic routines for memory allocation
14 -----------------------------------------------------------------------------
16 module Foreign.Marshal.Alloc (
18 malloc, -- :: Storable a => IO (Ptr a)
19 mallocBytes, -- :: Int -> IO (Ptr a)
21 alloca, -- :: Storable a => (Ptr a -> IO b) -> IO b
22 allocaBytes, -- :: Int -> (Ptr a -> IO b) -> IO b
24 realloc, -- :: Storable b => Ptr a -> IO (Ptr b)
25 reallocBytes, -- :: Ptr a -> Int -> IO (Ptr a)
27 free, -- :: Ptr a -> IO ()
28 finalizerFree -- :: FinalizerPtr a
32 import Foreign.Ptr ( Ptr, nullPtr, FunPtr )
33 import Foreign.C.Types ( CSize )
34 import Foreign.Storable ( Storable(sizeOf) )
36 #ifdef __GLASGOW_HASKELL__
37 import Foreign.ForeignPtr ( FinalizerPtr )
44 #elif defined(__NHC__)
45 import NHC.FFI ( FinalizerPtr, CInt(..) )
48 import Control.Exception ( bracket )
52 import Hugs.ForeignPtr ( FinalizerPtr )
59 -- |Allocate space for storable type. The size of the area allocated
60 -- is determined by the 'sizeOf' method from the instance of
61 -- 'Storable' for the appropriate type.
63 malloc :: Storable a => IO (Ptr a)
64 malloc = doMalloc undefined
66 doMalloc :: Storable a => a -> IO (Ptr a)
67 doMalloc dummy = mallocBytes (sizeOf dummy)
69 -- |Allocate given number of bytes of storage, equivalent to C\'s @malloc()@.
71 mallocBytes :: Int -> IO (Ptr a)
72 mallocBytes size = failWhenNULL "malloc" (_malloc (fromIntegral size))
74 -- |Temporarily allocate space for a storable type.
76 -- * the pointer passed as an argument to the function must /not/ escape from
77 -- this function; in other words, in @alloca f@ the allocated storage must
78 -- not be used after @f@ returns
80 alloca :: Storable a => (Ptr a -> IO b) -> IO b
81 alloca = doAlloca undefined
83 doAlloca :: Storable a => a -> (Ptr a -> IO b) -> IO b
84 doAlloca dummy = allocaBytes (sizeOf dummy)
86 -- |Temporarily allocate the given number of bytes of storage.
88 -- * the pointer passed as an argument to the function must /not/ escape from
89 -- this function; in other words, in @allocaBytes n f@ the allocated storage
90 -- must not be used after @f@ returns
92 #ifdef __GLASGOW_HASKELL__
93 allocaBytes :: Int -> (Ptr a -> IO b) -> IO b
94 allocaBytes (I# size) action = IO $ \ s ->
95 case newPinnedByteArray# size s of { (# s, mbarr# #) ->
96 case unsafeFreezeByteArray# mbarr# s of { (# s, barr# #) ->
97 let addr = Ptr (byteArrayContents# barr#) in
98 case action addr of { IO action ->
99 case action s of { (# s, r #) ->
100 case touch# barr# s of { s ->
104 allocaBytes :: Int -> (Ptr a -> IO b) -> IO b
105 allocaBytes size = bracket (mallocBytes size) free
108 -- |Adjust a malloc\'ed storage area to the given size of the required type
109 -- (corresponds to C\'s @realloc()@).
111 realloc :: Storable b => Ptr a -> IO (Ptr b)
112 realloc = doRealloc undefined
114 doRealloc :: Storable b => b -> Ptr a -> IO (Ptr b)
115 doRealloc dummy ptr = let
116 size = fromIntegral (sizeOf dummy)
118 failWhenNULL "realloc" (_realloc ptr size)
120 -- |Adjust a malloc\'ed storage area to the given size (equivalent to
121 -- C\'s @realloc()@).
123 reallocBytes :: Ptr a -> Int -> IO (Ptr a)
124 reallocBytes ptr 0 = do free ptr; return nullPtr
125 reallocBytes ptr size =
126 failWhenNULL "realloc" (_realloc ptr (fromIntegral size))
128 -- |Free malloc\'ed storage (equivalent to
131 free :: Ptr a -> IO ()
135 -- auxilliary routines
136 -- -------------------
138 -- asserts that the pointer returned from the action in the second argument is
141 failWhenNULL :: String -> IO (Ptr a) -> IO (Ptr a)
142 failWhenNULL name f = do
145 #ifdef __GLASGOW_HASKELL__
146 then ioException (IOError Nothing ResourceExhausted name
147 "out of memory" Nothing)
149 then ioError (userError (name++": out of memory"))
153 -- basic C routines needed for memory allocation
155 foreign import ccall unsafe "stdlib.h malloc" _malloc :: CSize -> IO (Ptr a)
156 foreign import ccall unsafe "stdlib.h realloc" _realloc :: Ptr a -> CSize -> IO (Ptr b)
157 foreign import ccall unsafe "stdlib.h free" _free :: Ptr a -> IO ()
159 -- | A pointer to a foreign function equivalent to 'free', which may be used
160 -- as a finalizer for storage allocated with 'malloc' or 'mallocBytes'.
161 foreign import ccall unsafe "stdlib.h &free" finalizerFree :: FinalizerPtr a