| Copyright | (c) The University of Glasgow 2001 |
|---|---|
| License | BSD-style (see the file libraries/base/LICENSE) |
| Maintainer | ffi@haskell.org |
| Stability | provisional |
| Portability | portable |
| Safe Haskell | Trustworthy |
| Language | Haskell2010 |
Foreign.StablePtr
Description
This module is part of the Foreign Function Interface (FFI) and will usually be imported via the module Foreign.
Synopsis
- data StablePtr a
- newStablePtr :: a -> IO (StablePtr a)
- deRefStablePtr :: StablePtr a -> IO a
- freeStablePtr :: StablePtr a -> IO ()
- castStablePtrToPtr :: StablePtr a -> Ptr ()
- castPtrToStablePtr :: Ptr () -> StablePtr a
Stable references to Haskell values
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.
The StablePtr 0 is reserved for representing NULL in foreign code.
A value of type StablePtr a is a stable pointer to a Haskell
expression of type a.
Instances
| Storable (StablePtr a) Source # | Since: base-2.1 |
Defined in Foreign.Storable Methods sizeOf :: StablePtr a -> Int Source # alignment :: StablePtr a -> Int Source # peekElemOff :: Ptr (StablePtr a) -> Int -> IO (StablePtr a) Source # pokeElemOff :: Ptr (StablePtr a) -> Int -> StablePtr a -> IO () Source # peekByteOff :: Ptr b -> Int -> IO (StablePtr a) Source # pokeByteOff :: Ptr b -> Int -> StablePtr a -> IO () Source # | |
| Eq (StablePtr a) Source # | Since: base-2.1 |
newStablePtr :: a -> IO (StablePtr a) Source #
Create a stable pointer referring to the given Haskell value.
deRefStablePtr :: StablePtr a -> IO a Source #
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 () Source #
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 () Source #
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 might 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 Source #
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.
The C-side interface
The following definition is available to C programs inter-operating with
Haskell code when including the header HsFFI.h.
typedef void *HsStablePtr; /* C representation of a StablePtr */
Note that no assumptions may be made about the values representing stable
pointers. In fact, they need not even be valid memory addresses. The only
guarantee provided is that if they are passed back to Haskell land, the
function deRefStablePtr will be able to reconstruct the
Haskell value referred to by the stable pointer.