|Copyright||(c) The University of Glasgow 1992-2004|
|Portability||non-portable (GHC Extensions)|
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
|Eq (StablePtr a)||
|Storable (StablePtr a)||
Defined in Foreign.Storable
Create a stable pointer referring to the given Haskell value.
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.
Dissolve the association between the stable pointer and the Haskell value. Afterwards, if the stable pointer is passed to
freeStablePtr, the behaviour is undefined. However, the stable pointer may still be passed to
castStablePtrToPtr, but the
Ptr () value returned by
castStablePtrToPtr, in this case, is undefined (in particular, it may be
nullPtr). Nevertheless, the call to
castStablePtrToPtr is guaranteed not to diverge.
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.
The inverse of
castStablePtrToPtr, i.e., we have the identity
sp == castPtrToStablePtr (castStablePtrToPtr sp)
© The University of Glasgow and others
Licensed under a BSD-style license (see top of the page).