Added Unknowns for higher kinds
[packages/random.git] / GHC / Stable.lhs
1 \begin{code}
2 {-# OPTIONS_GHC -fno-implicit-prelude #-}
3 -----------------------------------------------------------------------------
4 -- |
5 -- Module      :  GHC.Stable
6 -- Copyright   :  (c) The University of Glasgow, 1992-2004
7 -- License     :  see libraries/base/LICENSE
8 -- 
9 -- Maintainer  :  ffi@haskell.org
10 -- Stability   :  internal
11 -- Portability :  non-portable (GHC Extensions)
12 --
13 -- Stable pointers.
14 --
15 -----------------------------------------------------------------------------
16
17 -- #hide
18 module GHC.Stable 
19         ( StablePtr(..)
20         , newStablePtr          -- :: a -> IO (StablePtr a)    
21         , deRefStablePtr        -- :: StablePtr a -> a
22         , freeStablePtr         -- :: StablePtr a -> IO ()
23         , castStablePtrToPtr    -- :: StablePtr a -> Ptr ()
24         , castPtrToStablePtr    -- :: Ptr () -> StablePtr a
25    ) where
26
27 import GHC.Ptr
28 import GHC.Base
29 import GHC.IOBase
30
31 -----------------------------------------------------------------------------
32 -- Stable Pointers
33
34 {- |
35 A /stable pointer/ is a reference to a Haskell expression that is
36 guaranteed not to be affected by garbage collection, i.e., it will neither be
37 deallocated nor will the value of the stable pointer itself change during
38 garbage collection (ordinary references may be relocated during garbage
39 collection).  Consequently, stable pointers can be passed to foreign code,
40 which can treat it as an opaque reference to a Haskell value.
41
42 A value of type @StablePtr a@ is a stable pointer to a Haskell
43 expression of type @a@.
44 -}
45 data StablePtr a = StablePtr (StablePtr# a)
46
47 -- |
48 -- Create a stable pointer referring to the given Haskell value.
49 --
50 newStablePtr   :: a -> IO (StablePtr a)
51 newStablePtr a = IO $ \ s ->
52     case makeStablePtr# a s of (# s', sp #) -> (# s', StablePtr sp #)
53
54 -- |
55 -- Obtain the Haskell value referenced by a stable pointer, i.e., the
56 -- same value that was passed to the corresponding call to
57 -- 'makeStablePtr'.  If the argument to 'deRefStablePtr' has
58 -- already been freed using 'freeStablePtr', the behaviour of
59 -- 'deRefStablePtr' is undefined.
60 --
61 deRefStablePtr :: StablePtr a -> IO a
62 deRefStablePtr (StablePtr sp) = IO $ \s -> deRefStablePtr# sp s
63
64 -- |
65 -- Dissolve the association between the stable pointer and the Haskell
66 -- value. Afterwards, if the stable pointer is passed to
67 -- 'deRefStablePtr' or 'freeStablePtr', the behaviour is
68 -- undefined.  However, the stable pointer may still be passed to
69 -- 'castStablePtrToPtr', but the @'Foreign.Ptr.Ptr' ()@ value returned
70 -- by 'castStablePtrToPtr', in this case, is undefined (in particular,
71 -- it may be 'Foreign.Ptr.nullPtr').  Nevertheless, the call
72 -- to 'castStablePtrToPtr' is guaranteed not to diverge.
73 --
74 foreign import ccall unsafe "hs_free_stable_ptr" freeStablePtr :: StablePtr a -> IO ()
75
76 -- |
77 -- Coerce a stable pointer to an address. No guarantees are made about
78 -- the resulting value, except that the original stable pointer can be
79 -- recovered by 'castPtrToStablePtr'.  In particular, the address may not
80 -- refer to an accessible memory location and any attempt to pass it to
81 -- the member functions of the class 'Foreign.Storable.Storable' leads to
82 -- undefined behaviour.
83 --
84 castStablePtrToPtr :: StablePtr a -> Ptr ()
85 castStablePtrToPtr (StablePtr s) = Ptr (unsafeCoerce# s)
86
87
88 -- |
89 -- The inverse of 'castStablePtrToPtr', i.e., we have the identity
90 -- 
91 -- > sp == castPtrToStablePtr (castStablePtrToPtr sp)
92 -- 
93 -- for any stable pointer @sp@ on which 'freeStablePtr' has
94 -- not been executed yet.  Moreover, 'castPtrToStablePtr' may
95 -- only be applied to pointers that have been produced by
96 -- 'castStablePtrToPtr'.
97 --
98 castPtrToStablePtr :: Ptr () -> StablePtr a
99 castPtrToStablePtr (Ptr a) = StablePtr (unsafeCoerce# a)
100
101 instance Eq (StablePtr a) where 
102     (StablePtr sp1) == (StablePtr sp2) =
103         case eqStablePtr# sp1 sp2 of
104            0# -> False
105            _  -> True
106 \end{code}