| Copyright | (c) The University of Glasgow 1992-2004 | 
|---|---|
| License | see libraries/base/LICENSE | 
| Maintainer | ffi@haskell.org | 
| Stability | internal | 
| Portability | non-portable (GHC Extensions) | 
| Safe Haskell | Unsafe | 
| Language | Haskell2010 | 
GHC.Stable
Description
Stable pointers.
Synopsis
- data StablePtr a = StablePtr (StablePtr# a)
- newStablePtr :: a -> IO (StablePtr a)
- deRefStablePtr :: StablePtr a -> IO a
- freeStablePtr :: StablePtr a -> IO ()
- castStablePtrToPtr :: StablePtr a -> Ptr ()
- castPtrToStablePtr :: Ptr () -> StablePtr a
Documentation
A stable pointer is a reference to a Haskell expression that is guaranteed not to be affected by garbage collection, i.e., it will neither be deallocated nor will the value of the stable pointer itself change during garbage collection (ordinary references may be relocated during garbage collection). Consequently, stable pointers can be passed to foreign code, which can treat it as an opaque reference to a Haskell value.
A value of type StablePtr a is a stable pointer to a Haskell
expression of type a.
Constructors
| StablePtr (StablePtr# a) | 
Instances
| Storable (StablePtr a) # | Since: base-2.1 | 
| Defined in Foreign.Storable Methods sizeOf :: StablePtr a -> Int # alignment :: StablePtr a -> Int # peekElemOff :: Ptr (StablePtr a) -> Int -> IO (StablePtr a) # pokeElemOff :: Ptr (StablePtr a) -> Int -> StablePtr a -> IO () # peekByteOff :: Ptr b -> Int -> IO (StablePtr a) # pokeByteOff :: Ptr b -> Int -> StablePtr a -> IO () # | |
| Eq (StablePtr a) # | Since: base-2.1 | 
newStablePtr :: a -> IO (StablePtr a) #
Create a stable pointer referring to the given Haskell value.
deRefStablePtr :: StablePtr a -> IO a #
Obtain the Haskell value referenced by a stable pointer, i.e., the
 same value that was passed to the corresponding call to
 newStablePtr.  If the argument to deRefStablePtr has
 already been freed using freeStablePtr, the behaviour of
 deRefStablePtr is undefined.
freeStablePtr :: StablePtr a -> IO () #
Dissolve the association between the stable pointer and the Haskell
 value. Afterwards, if the stable pointer is passed to
 deRefStablePtr or freeStablePtr, the behaviour is
 undefined.  However, the stable pointer may still be passed to
 castStablePtrToPtr, but the Ptr ()castStablePtrToPtr, in this case, is undefined (in particular,
 it may be nullPtr).  Nevertheless, the call
 to castStablePtrToPtr is guaranteed not to diverge.
castStablePtrToPtr :: StablePtr a -> Ptr () #
Coerce a stable pointer to an address. No guarantees are made about
 the resulting value, except that the original stable pointer can be
 recovered by castPtrToStablePtr.  In particular, the address may not
 refer to an accessible memory location and any attempt to pass it to
 the member functions of the class Storable leads to
 undefined behaviour.
castPtrToStablePtr :: Ptr () -> StablePtr a #
The inverse of castStablePtrToPtr, i.e., we have the identity
sp == castPtrToStablePtr (castStablePtrToPtr sp)
for any stable pointer sp on which freeStablePtr has
 not been executed yet.  Moreover, castPtrToStablePtr may
 only be applied to pointers that have been produced by
 castStablePtrToPtr.