Add explicit `{-# LANGUAGE CPP, PackageImports #-}` pragmas
[packages/haskell2010.git] / Foreign / Marshal / Alloc.hs
1 {-# LANGUAGE CPP, PackageImports #-}
2 #if __GLASGOW_HASKELL__ >= 701
3 {-# LANGUAGE Safe #-}
4 #endif
5
6 {- |
7 The module "Foreign.Marshal.Alloc" provides operations to allocate and
8 deallocate blocks of raw memory (i.e., unstructured chunks of memory
9 outside of the area maintained by the Haskell storage manager). These
10 memory blocks are commonly used to pass compound data structures to
11 foreign functions or to provide space in which compound result values
12 are obtained from foreign functions.
13
14 If any of the allocation functions fails, a value of 'nullPtr' is
15 produced. If 'free' or 'reallocBytes' is applied to a memory area
16 that has been allocated with 'alloca' or 'allocaBytes', the
17 behaviour is undefined. Any further access to memory areas allocated with
18 'alloca' or 'allocaBytes', after the computation that was passed to
19 the allocation function has terminated, leads to undefined behaviour. Any
20 further access to the memory area referenced by a pointer passed to
21 'realloc', 'reallocBytes', or 'free' entails undefined
22 behaviour.
23
24 All storage allocated by functions that allocate based on a /size in bytes/
25 must be sufficiently aligned for any of the basic foreign types
26 that fits into the newly allocated storage. All storage allocated by
27 functions that allocate based on a specific type must be sufficiently
28 aligned for that type. Array allocation routines need to obey the same
29 alignment constraints for each array element.
30 -}
31 module Foreign.Marshal.Alloc (
32 -- * Memory allocation
33 -- ** Local allocation
34 alloca, -- :: Storable a => (Ptr a -> IO b) -> IO b
35 allocaBytes, -- :: Int -> (Ptr a -> IO b) -> IO b
36
37 -- ** Dynamic allocation
38 malloc, -- :: Storable a => IO (Ptr a)
39 mallocBytes, -- :: Int -> IO (Ptr a)
40
41 realloc, -- :: Storable b => Ptr a -> IO (Ptr b)
42 reallocBytes, -- :: Ptr a -> Int -> IO (Ptr a)
43
44 free, -- :: Ptr a -> IO ()
45 finalizerFree -- :: FinalizerPtr a
46 ) where
47 import "base" Foreign.Marshal.Alloc