| Safe Haskell | None |
|---|---|
| Language | Haskell2010 |
Haskus.Memory.Ptr
Description
Pointers
A pointer is a number: an offset into a memory. This is the `Addr#` type.
We want the type-system to help us avoid errors when we use pointers, hence we decorate them with phantom types describing the memory layout at the pointed address. This is the `Ptr a` data type that wraps an `Addr#`.
We often want to associate finalizers to pointers, i.e., actions to be run when the pointer is collected by the GC. These actions take the pointer as a parameter. This is the `ForeignPtr a` data type.
A `ForeignPtr a` cannot be manipulated like a number because somehow we need to keep the pointer value that will be passed to the finalizers. Moreover we don't want finalizers to be executed too early, so we can't easily create a new ForeignPtr from another (it would require a way to disable the existing finalizers of a ForeignPtr, which would in turn open a whole can of worms). Hence we use the `FinalizedPtr a` pointer type, which has an additional offset field.
Synopsis
- data Pointer (mut :: Mutability) (fin :: Finalization) where
- newtype AnyPointer = AnyPointer (forall mut fin. Pointer mut fin)
- type RawPtr = Ptr ()
- type FinPtr = ForeignPtr ()
- type PtrI = Pointer Immutable NotFinalized
- type PtrM = Pointer Mutable NotFinalized
- type PtrIF = Pointer Immutable Finalized
- type PtrMF = Pointer Mutable Finalized
- isNullPtr :: Pointer mut fin -> Bool
- nullPtrI :: PtrI
- nullPtrM :: PtrM
- indexPtr :: Pointer mut fin -> Int -> Pointer mut fin
- distancePtr :: Pointer mut0 fin0 -> Pointer mut1 fin1 -> Int
- withPtr :: MonadInIO m => Pointer mut fin -> (Pointer mut NotFinalized -> m b) -> m b
- withFinalizedPtr :: MonadInIO m => Pointer mut Finalized -> (Pointer mut NotFinalized -> m b) -> m b
- allocFinalizedPtr :: MonadIO m => Word -> m PtrMF
- allocPtr :: MonadIO m => Word -> m PtrM
- freePtr :: MonadIO m => Pointer mut NotFinalized -> m ()
- data FunPtr a
- nullFunPtr :: FunPtr a
- castPtrToFunPtr :: Ptr a -> FunPtr b
- castFunPtrToPtr :: FunPtr a -> Ptr b
- data WordPtr
- wordPtrToPtr :: WordPtr -> Ptr a
- ptrToWordPtr :: Ptr a -> WordPtr
Documentation
data Pointer (mut :: Mutability) (fin :: Finalization) where Source #
A pointer in memory
newtype AnyPointer Source #
Wrapper containing any kind of buffer
Constructors
| AnyPointer (forall mut fin. Pointer mut fin) |
type FinPtr = ForeignPtr () Source #
withPtr :: MonadInIO m => Pointer mut fin -> (Pointer mut NotFinalized -> m b) -> m b Source #
Use a pointer (finalized or not) as a non finalized pointer
withFinalizedPtr :: MonadInIO m => Pointer mut Finalized -> (Pointer mut NotFinalized -> m b) -> m b Source #
Use a finalized pointer as a non finalized pointer
Function pointer
A value of type FunPtr aa will normally be a foreign type,
a function type with zero or more arguments where
- the argument types are marshallable foreign types,
i.e.
Char,Int,Double,Float,Bool,Int8,Int16,Int32,Int64,Word8,Word16,Word32,Word64,PtraFunPtraStablePtranewtype. - the return type is either a marshallable foreign type or has the form
IOttis a marshallable foreign type or().
A value of type FunPtr a
foreign import ccall "stdlib.h &free" p_free :: FunPtr (Ptr a -> IO ())
or a pointer to a Haskell function created using a wrapper stub
declared to produce a FunPtr of the correct type. For example:
type Compare = Int -> Int -> Bool foreign import ccall "wrapper" mkCompare :: Compare -> IO (FunPtr Compare)
Calls to wrapper stubs like mkCompare allocate storage, which
should be released with freeHaskellFunPtr when no
longer required.
To convert FunPtr values to corresponding Haskell functions, one
can define a dynamic stub for the specific foreign type, e.g.
type IntFunction = CInt -> IO () foreign import ccall "dynamic" mkFun :: FunPtr IntFunction -> IntFunction
Instances
| Eq (FunPtr a) | |
| Ord (FunPtr a) | |
Defined in GHC.Ptr | |
| Show (FunPtr a) | Since: base-2.1 |
| Storable (FunPtr a) | Since: base-2.1 |
Defined in Foreign.Storable | |
nullFunPtr :: FunPtr a #
The constant nullFunPtr contains a
distinguished value of FunPtr that is not
associated with a valid memory location.
castPtrToFunPtr :: Ptr a -> FunPtr b #
castFunPtrToPtr :: FunPtr a -> Ptr b #
Pointer as a Word
An unsigned integral type that can be losslessly converted to and from
Ptr. This type is also compatible with the C99 type uintptr_t, and
can be marshalled to and from that type safely.
Instances
wordPtrToPtr :: WordPtr -> Ptr a #
casts a WordPtr to a Ptr
ptrToWordPtr :: Ptr a -> WordPtr #
casts a Ptr to a WordPtr