Safe Haskell | None |
---|---|
Language | Haskell2010 |
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
- class PtrLike (p :: * -> *) where
- indexPtr' :: Integral b => Ptr a -> b -> Ptr a
- data Ptr a = Ptr Addr#
- free :: MonadIO m => Ptr a -> m ()
- data FinalizedPtr l = FinalizedPtr !(ForeignPtr l) !Word
- withFinalizedPtr :: FinalizedPtr a -> (Ptr a -> IO b) -> IO b
- data ForeignPtr a
- withForeignPtr :: MonadInIO m => ForeignPtr a -> (Ptr a -> m b) -> m b
- mallocForeignPtrBytes :: MonadIO m => Word -> m (ForeignPtr a)
- nullForeignPtr :: ForeignPtr a
- 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
class PtrLike (p :: * -> *) where Source #
Pointer operations
castPtr :: p a -> p b Source #
Cast a pointer from one type to another
nullPtr :: forall a. p a Source #
Null pointer (offset is 0)
indexPtr :: p a -> Int -> p a Source #
Advance a pointer by the given amount of bytes (may be negative)
ptrDistance :: p a -> p b -> Int Source #
Distance between two pointers in bytes (p2 - p1)
withPtr :: p a -> (Ptr a -> IO b) -> IO b Source #
Use the pointer
mallocBytes :: MonadIO m => Word -> m (p a) Source #
Malloc the given number of bytes
indexField :: forall path l. KnownNat (LayoutPathOffset l path) => p l -> path -> p (LayoutPathType l path) Source #
Add offset to the given layout field
(-->) :: forall s l. KnownNat (LayoutPathOffset l (LayoutPath '[LayoutSymbol s])) => p l -> LayoutSymbol s -> p (LayoutPathType l (LayoutPath '[LayoutSymbol s])) Source #
Add offset corresponding to the layout field with the given symbol
(-#>) :: forall n l. KnownNat (LayoutPathOffset l (LayoutPath '[LayoutIndex n])) => p l -> LayoutIndex n -> p (LayoutPathType l (LayoutPath '[LayoutIndex n])) Source #
Add offset corresponding to the layout field with the given index
Instances
Pointer
A value of type
represents a pointer to an object, or an
array of objects, which may be marshalled to or from Haskell values
of type Ptr
aa
.
The type a
will often be an instance of class
Storable
which provides the marshalling operations.
However this is not essential, and you can provide your own operations
to access the pointer. For example you might write small foreign
functions to get or set the fields of a C struct
.
Instances
PtrLike Ptr Source # | |
Defined in Haskus.Format.Binary.Ptr castPtr :: Ptr a -> Ptr b Source # indexPtr :: Ptr a -> Int -> Ptr a Source # ptrDistance :: Ptr a -> Ptr b -> Int Source # withPtr :: Ptr a -> (Ptr a -> IO b) -> IO b Source # mallocBytes :: MonadIO m => Word -> m (Ptr a) Source # indexField :: KnownNat (LayoutPathOffset l path) => Ptr l -> path -> Ptr (LayoutPathType l path) Source # (-->) :: KnownNat (LayoutPathOffset l (LayoutPath (LayoutSymbol s ': []))) => Ptr l -> LayoutSymbol s -> Ptr (LayoutPathType l (LayoutPath (LayoutSymbol s ': []))) Source # (-#>) :: KnownNat (LayoutPathOffset l (LayoutPath (LayoutIndex n ': []))) => Ptr l -> LayoutIndex n -> Ptr (LayoutPathType l (LayoutPath (LayoutIndex n ': []))) Source # | |
Generic1 (URec (Ptr ()) :: k -> *) | |
Eq (Ptr a) | |
Data a => Data (Ptr a) | Since: base-4.8.0.0 |
Defined in Data.Data gfoldl :: (forall d b. Data d => c (d -> b) -> d -> c b) -> (forall g. g -> c g) -> Ptr a -> c (Ptr a) # gunfold :: (forall b r. Data b => c (b -> r) -> c r) -> (forall r. r -> c r) -> Constr -> c (Ptr a) # dataTypeOf :: Ptr a -> DataType # dataCast1 :: Typeable t => (forall d. Data d => c (t d)) -> Maybe (c (Ptr a)) # dataCast2 :: Typeable t => (forall d e. (Data d, Data e) => c (t d e)) -> Maybe (c (Ptr a)) # gmapT :: (forall b. Data b => b -> b) -> Ptr a -> Ptr a # gmapQl :: (r -> r' -> r) -> r -> (forall d. Data d => d -> r') -> Ptr a -> r # gmapQr :: (r' -> r -> r) -> r -> (forall d. Data d => d -> r') -> Ptr a -> r # gmapQ :: (forall d. Data d => d -> u) -> Ptr a -> [u] # gmapQi :: Int -> (forall d. Data d => d -> u) -> Ptr a -> u # gmapM :: Monad m => (forall d. Data d => d -> m d) -> Ptr a -> m (Ptr a) # gmapMp :: MonadPlus m => (forall d. Data d => d -> m d) -> Ptr a -> m (Ptr a) # gmapMo :: MonadPlus m => (forall d. Data d => d -> m d) -> Ptr a -> m (Ptr a) # | |
Ord (Ptr a) | |
Show (Ptr a) | Since: base-2.1 |
Storable (Ptr a) | Since: base-2.1 |
Storable (Ptr a) Source # | |
Functor (URec (Ptr ()) :: * -> *) | |
Foldable (URec (Ptr ()) :: * -> *) | |
Defined in Data.Foldable fold :: Monoid m => URec (Ptr ()) m -> m # foldMap :: Monoid m => (a -> m) -> URec (Ptr ()) a -> m # foldr :: (a -> b -> b) -> b -> URec (Ptr ()) a -> b # foldr' :: (a -> b -> b) -> b -> URec (Ptr ()) a -> b # foldl :: (b -> a -> b) -> b -> URec (Ptr ()) a -> b # foldl' :: (b -> a -> b) -> b -> URec (Ptr ()) a -> b # foldr1 :: (a -> a -> a) -> URec (Ptr ()) a -> a # foldl1 :: (a -> a -> a) -> URec (Ptr ()) a -> a # toList :: URec (Ptr ()) a -> [a] # null :: URec (Ptr ()) a -> Bool # length :: URec (Ptr ()) a -> Int # elem :: Eq a => a -> URec (Ptr ()) a -> Bool # maximum :: Ord a => URec (Ptr ()) a -> a # minimum :: Ord a => URec (Ptr ()) a -> a # | |
Traversable (URec (Ptr ()) :: * -> *) | |
Defined in Data.Traversable | |
Eq (URec (Ptr ()) p) | |
Ord (URec (Ptr ()) p) | |
Defined in GHC.Generics compare :: URec (Ptr ()) p -> URec (Ptr ()) p -> Ordering # (<) :: URec (Ptr ()) p -> URec (Ptr ()) p -> Bool # (<=) :: URec (Ptr ()) p -> URec (Ptr ()) p -> Bool # (>) :: URec (Ptr ()) p -> URec (Ptr ()) p -> Bool # (>=) :: URec (Ptr ()) p -> URec (Ptr ()) p -> Bool # max :: URec (Ptr ()) p -> URec (Ptr ()) p -> URec (Ptr ()) p # min :: URec (Ptr ()) p -> URec (Ptr ()) p -> URec (Ptr ()) p # | |
Generic (URec (Ptr ()) p) | |
data URec (Ptr ()) (p :: k) | Used for marking occurrences of Since: base-4.9.0.0 |
type Rep1 (URec (Ptr ()) :: k -> *) | |
Defined in GHC.Generics | |
type Rep (URec (Ptr ()) p) | |
Defined in GHC.Generics |
Finalized pointer
data FinalizedPtr l Source #
A finalized pointer
We use an offset because we can't modify the pointer directly (it is passed to the foreign pointer destructors)
FinalizedPtr !(ForeignPtr l) !Word |
Instances
withFinalizedPtr :: FinalizedPtr a -> (Ptr a -> IO b) -> IO b Source #
Use a finalized pointer
Foreign pointer
data ForeignPtr a #
The type ForeignPtr
represents references to objects that are
maintained in a foreign language, i.e., that are not part of the
data structures usually managed by the Haskell storage manager.
The essential difference between ForeignPtr
s and vanilla memory
references of type Ptr a
is that the former may be associated
with finalizers. A finalizer is a routine that is invoked when
the Haskell storage manager detects that - within the Haskell heap
and stack - there are no more references left that are pointing to
the ForeignPtr
. Typically, the finalizer will, then, invoke
routines in the foreign language that free the resources bound by
the foreign object.
The ForeignPtr
is parameterised in the same way as Ptr
. The
type argument of ForeignPtr
should normally be an instance of
class Storable
.
Instances
Eq (ForeignPtr a) | Since: base-2.1 |
Defined in GHC.ForeignPtr (==) :: ForeignPtr a -> ForeignPtr a -> Bool # (/=) :: ForeignPtr a -> ForeignPtr a -> Bool # | |
Data a => Data (ForeignPtr a) | Since: base-4.8.0.0 |
Defined in Data.Data gfoldl :: (forall d b. Data d => c (d -> b) -> d -> c b) -> (forall g. g -> c g) -> ForeignPtr a -> c (ForeignPtr a) # gunfold :: (forall b r. Data b => c (b -> r) -> c r) -> (forall r. r -> c r) -> Constr -> c (ForeignPtr a) # toConstr :: ForeignPtr a -> Constr # dataTypeOf :: ForeignPtr a -> DataType # dataCast1 :: Typeable t => (forall d. Data d => c (t d)) -> Maybe (c (ForeignPtr a)) # dataCast2 :: Typeable t => (forall d e. (Data d, Data e) => c (t d e)) -> Maybe (c (ForeignPtr a)) # gmapT :: (forall b. Data b => b -> b) -> ForeignPtr a -> ForeignPtr a # gmapQl :: (r -> r' -> r) -> r -> (forall d. Data d => d -> r') -> ForeignPtr a -> r # gmapQr :: (r' -> r -> r) -> r -> (forall d. Data d => d -> r') -> ForeignPtr a -> r # gmapQ :: (forall d. Data d => d -> u) -> ForeignPtr a -> [u] # gmapQi :: Int -> (forall d. Data d => d -> u) -> ForeignPtr a -> u # gmapM :: Monad m => (forall d. Data d => d -> m d) -> ForeignPtr a -> m (ForeignPtr a) # gmapMp :: MonadPlus m => (forall d. Data d => d -> m d) -> ForeignPtr a -> m (ForeignPtr a) # gmapMo :: MonadPlus m => (forall d. Data d => d -> m d) -> ForeignPtr a -> m (ForeignPtr a) # | |
Ord (ForeignPtr a) | Since: base-2.1 |
Defined in GHC.ForeignPtr compare :: ForeignPtr a -> ForeignPtr a -> Ordering # (<) :: ForeignPtr a -> ForeignPtr a -> Bool # (<=) :: ForeignPtr a -> ForeignPtr a -> Bool # (>) :: ForeignPtr a -> ForeignPtr a -> Bool # (>=) :: ForeignPtr a -> ForeignPtr a -> Bool # max :: ForeignPtr a -> ForeignPtr a -> ForeignPtr a # min :: ForeignPtr a -> ForeignPtr a -> ForeignPtr a # | |
Show (ForeignPtr a) | Since: base-2.1 |
Defined in GHC.ForeignPtr showsPrec :: Int -> ForeignPtr a -> ShowS # show :: ForeignPtr a -> String # showList :: [ForeignPtr a] -> ShowS # |
withForeignPtr :: MonadInIO m => ForeignPtr a -> (Ptr a -> m b) -> m b Source #
Use a foreign pointer
mallocForeignPtrBytes :: MonadIO m => Word -> m (ForeignPtr a) Source #
Malloc a foreign pointer
nullForeignPtr :: ForeignPtr a Source #
Null foreign pointer
Function pointer
A value of type
is a pointer to a function callable
from foreign code. The 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
,
,Ptr
a
,FunPtr
a
or a renaming of any of these usingStablePtr
anewtype
. - the return type is either a marshallable foreign type or has the form
whereIO
tt
is a marshallable foreign type or()
.
A value of type
may be a pointer to a foreign function,
either returned by another foreign function or imported with a
a static address import likeFunPtr
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) | |
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