base-4.20.2.0: Core data structures and operations

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 | None
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

data StablePtr a Source #

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`.

Constructors

StablePtr (StablePtr# a) |

#### Instances

Instances details

Storable (StablePtr a) | Since: base-2.1

Instance details

Defined in GHC.Internal.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 #

peek :: Ptr (StablePtr a) -> IO (StablePtr a) Source #

poke :: Ptr (StablePtr a) -> StablePtr a -> IO () Source #

Eq (StablePtr a) | Since: base-2.1
Instance details Defined in GHC.Internal.Stable Methods (==) :: StablePtr a -> StablePtr a -> Bool Source # (/=) :: StablePtr a -> StablePtr a -> Bool Source #

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` ()` 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.

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`.