1fd58652f9e0f86313b576daa917cc55a4340b49
[packages/haskell2010.git] / Foreign / ForeignPtr.hs
1 {-# LANGUAGE PackageImports #-}
2
3 module Foreign.ForeignPtr (
4 -- * Finalised data pointers
5 ForeignPtr
6 , FinalizerPtr
7 , FinalizerEnvPtr
8
9 -- ** Basic operations
10 , newForeignPtr
11 , newForeignPtr_
12 , addForeignPtrFinalizer
13 , newForeignPtrEnv
14 , addForeignPtrFinalizerEnv
15 , withForeignPtr
16 , finalizeForeignPtr
17
18 -- ** Low-level operations
19 , unsafeForeignPtrToPtr
20 , touchForeignPtr
21 , castForeignPtr
22
23 -- ** Allocating managed memory
24 , mallocForeignPtr
25 , mallocForeignPtrBytes
26 , mallocForeignPtrArray
27 , mallocForeignPtrArray0
28 ) where
29
30 import qualified "base" Foreign.ForeignPtr as Base
31 import "base" Foreign.ForeignPtr hiding (mallocForeignPtr, touchForeignPtr)
32 import "base" Foreign.ForeignPtr.Unsafe
33 import "base" Foreign (Storable)
34
35 -- SDM: local copy of the docs for mallocForeignPtr, to omit the
36 -- GHC-specific bits.
37
38 mallocForeignPtr :: Storable a => IO (ForeignPtr a)
39 -- ^ Allocate some memory and return a 'ForeignPtr' to it. The memory
40 -- will be released automatically when the 'ForeignPtr' is discarded.
41 --
42 -- 'mallocForeignPtr' is equivalent to
43 --
44 -- > do { p <- malloc; newForeignPtr finalizerFree p }
45 --
46 -- although it may be implemented differently internally: you may not
47 -- assume that the memory returned by 'mallocForeignPtr' has been
48 -- allocated with 'Foreign.Marshal.Alloc.malloc'.
49 mallocForeignPtr = Base.mallocForeignPtr
50
51 -- SDM: reproduced documentation for touchForeignPtr without reference
52 -- to Haskell finalizers and MVars.
53
54 touchForeignPtr :: ForeignPtr a -> IO ()
55 -- ^This function ensures that the foreign object in
56 -- question is alive at the given place in the sequence of IO
57 -- actions. In particular 'Foreign.ForeignPtr.withForeignPtr'
58 -- does a 'touchForeignPtr' after it
59 -- executes the user action.
60 --
61 -- Note that this function should not be used to express dependencies
62 -- between finalizers on 'ForeignPtr's. For example, if the finalizer
63 -- for a 'ForeignPtr' @F1@ calls 'touchForeignPtr' on a second
64 -- 'ForeignPtr' @F2@, then the only guarantee is that the finalizer
65 -- for @F2@ is never started before the finalizer for @F1@. They
66 -- might be started together if for example both @F1@ and @F2@ are
67 -- otherwise unreachable.
68 --
69 -- In general, it is not recommended to use finalizers on separate
70 -- objects with ordering constraints between them. To express the
71 -- ordering robustly requires explicit synchronisation between
72 -- finalizers.
73 --
74 touchForeignPtr = Base.touchForeignPtr