haskus-system-0.6.0.0: Haskus system programming framework

Safe HaskellNone
LanguageHaskell2010

Haskus.Format.Binary.Ptr

Contents

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

Documentation

class PtrLike p where Source #

Pointer operations

Minimal complete definition

nullPtr, indexPtr, ptrDistance, withPtr, mallocBytes

Methods

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

PtrLike Ptr Source # 

Methods

castPtr :: Ptr a -> Ptr b Source #

nullPtr :: Ptr a 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 #

PtrLike FinalizedPtr Source # 

indexPtr' :: Integral b => Ptr a -> b -> Ptr a Source #

Generalized version of indexPtr

Pointer

data Ptr a :: * -> * #

A value of type Ptr a represents a pointer to an object, or an array of objects, which may be marshalled to or from Haskell values of type a.

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.

Constructors

Ptr Addr# 

Instances

PtrLike Ptr Source # 

Methods

castPtr :: Ptr a -> Ptr b Source #

nullPtr :: Ptr a 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 #

IArray UArray (Ptr a) 

Methods

bounds :: Ix i => UArray i (Ptr a) -> (i, i) #

numElements :: Ix i => UArray i (Ptr a) -> Int

unsafeArray :: Ix i => (i, i) -> [(Int, Ptr a)] -> UArray i (Ptr a)

unsafeAt :: Ix i => UArray i (Ptr a) -> Int -> Ptr a

unsafeReplace :: Ix i => UArray i (Ptr a) -> [(Int, Ptr a)] -> UArray i (Ptr a)

unsafeAccum :: Ix i => (Ptr a -> e' -> Ptr a) -> UArray i (Ptr a) -> [(Int, e')] -> UArray i (Ptr a)

unsafeAccumArray :: Ix i => (Ptr a -> e' -> Ptr a) -> Ptr a -> (i, i) -> [(Int, e')] -> UArray i (Ptr a)

Eq (Ptr a) 

Methods

(==) :: Ptr a -> Ptr a -> Bool #

(/=) :: Ptr a -> Ptr a -> Bool #

Data a => Data (Ptr a) 

Methods

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) #

toConstr :: Ptr a -> Constr #

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) #

Functor (URec (Ptr ())) 

Methods

fmap :: (a -> b) -> URec (Ptr ()) a -> URec (Ptr ()) b #

(<$) :: a -> URec (Ptr ()) b -> URec (Ptr ()) a #

Ord (Ptr a) 

Methods

compare :: Ptr a -> Ptr a -> Ordering #

(<) :: Ptr a -> Ptr a -> Bool #

(<=) :: Ptr a -> Ptr a -> Bool #

(>) :: Ptr a -> Ptr a -> Bool #

(>=) :: Ptr a -> Ptr a -> Bool #

max :: Ptr a -> Ptr a -> Ptr a #

min :: Ptr a -> Ptr a -> Ptr a #

Show (Ptr a) 

Methods

showsPrec :: Int -> Ptr a -> ShowS #

show :: Ptr a -> String #

showList :: [Ptr a] -> ShowS #

Foldable (URec (Ptr ())) 

Methods

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 #

sum :: Num a => URec (Ptr ()) a -> a #

product :: Num a => URec (Ptr ()) a -> a #

Traversable (URec (Ptr ())) 

Methods

traverse :: Applicative f => (a -> f b) -> URec (Ptr ()) a -> f (URec (Ptr ()) b) #

sequenceA :: Applicative f => URec (Ptr ()) (f a) -> f (URec (Ptr ()) a) #

mapM :: Monad m => (a -> m b) -> URec (Ptr ()) a -> m (URec (Ptr ()) b) #

sequence :: Monad m => URec (Ptr ()) (m a) -> m (URec (Ptr ()) a) #

Generic1 (URec (Ptr ())) 

Associated Types

type Rep1 (URec (Ptr ()) :: * -> *) :: * -> * #

Methods

from1 :: URec (Ptr ()) a -> Rep1 (URec (Ptr ())) a #

to1 :: Rep1 (URec (Ptr ())) a -> URec (Ptr ()) a #

Storable (Ptr a) 

Methods

sizeOf :: Ptr a -> Int #

alignment :: Ptr a -> Int #

peekElemOff :: Ptr (Ptr a) -> Int -> IO (Ptr a) #

pokeElemOff :: Ptr (Ptr a) -> Int -> Ptr a -> IO () #

peekByteOff :: Ptr b -> Int -> IO (Ptr a) #

pokeByteOff :: Ptr b -> Int -> Ptr a -> IO () #

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

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

Hashable (Ptr a) 

Methods

hashWithSalt :: Int -> Ptr a -> Int #

hash :: Ptr a -> Int #

Buildable (Ptr a) 

Methods

build :: Ptr a -> Builder #

Storable (Ptr a) Source # 

Methods

peekIO :: Ptr (Ptr a) -> IO (Ptr a) Source #

pokeIO :: Ptr (Ptr a) -> Ptr a -> IO () Source #

alignment :: Ptr a -> Word Source #

sizeOf :: Ptr a -> Word Source #

Arg (Ptr a) Source # 

Methods

toArg :: Ptr a -> Int64 Source #

MArray (STUArray s) (Ptr a) (ST s) 

Methods

getBounds :: Ix i => STUArray s i (Ptr a) -> ST s (i, i) #

getNumElements :: Ix i => STUArray s i (Ptr a) -> ST s Int

newArray :: Ix i => (i, i) -> Ptr a -> ST s (STUArray s i (Ptr a)) #

newArray_ :: Ix i => (i, i) -> ST s (STUArray s i (Ptr a)) #

unsafeNewArray_ :: Ix i => (i, i) -> ST s (STUArray s i (Ptr a))

unsafeRead :: Ix i => STUArray s i (Ptr a) -> Int -> ST s (Ptr a)

unsafeWrite :: Ix i => STUArray s i (Ptr a) -> Int -> Ptr a -> ST s ()

Eq (URec (Ptr ()) p) 

Methods

(==) :: URec (Ptr ()) p -> URec (Ptr ()) p -> Bool #

(/=) :: URec (Ptr ()) p -> URec (Ptr ()) p -> Bool #

Ord (URec (Ptr ()) p) 

Methods

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) 

Associated Types

type Rep (URec (Ptr ()) p) :: * -> * #

Methods

from :: URec (Ptr ()) p -> Rep (URec (Ptr ()) p) x #

to :: Rep (URec (Ptr ()) p) x -> URec (Ptr ()) p #

type Rep1 (URec (Ptr ())) 
type Rep1 (URec (Ptr ())) = D1 (MetaData "URec" "GHC.Generics" "base" False) (C1 (MetaCons "UAddr" PrefixI True) (S1 (MetaSel (Just Symbol "uAddr#") NoSourceUnpackedness NoSourceStrictness DecidedLazy) UAddr))
data URec (Ptr ())

Used for marking occurrences of Addr#

data URec (Ptr ()) = UAddr {}
type Rep (URec (Ptr ()) p) 
type Rep (URec (Ptr ()) p) = D1 (MetaData "URec" "GHC.Generics" "base" False) (C1 (MetaCons "UAddr" PrefixI True) (S1 (MetaSel (Just Symbol "uAddr#") NoSourceUnpackedness NoSourceStrictness DecidedLazy) UAddr))

free :: MonadIO m => Ptr a -> m () Source #

Free a malloced memory

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)

Constructors

FinalizedPtr !(ForeignPtr l) !Word 

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 ForeignPtrs 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) 

Methods

(==) :: ForeignPtr a -> ForeignPtr a -> Bool #

(/=) :: ForeignPtr a -> ForeignPtr a -> Bool #

Data a => Data (ForeignPtr a) 

Methods

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) 
Show (ForeignPtr a) 

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

data FunPtr a :: * -> * #

A value of type FunPtr a is a pointer to a function callable from foreign code. The type a will normally be a foreign type, a function type with zero or more arguments where

A value of type FunPtr a may be a pointer to a foreign function, either returned by another foreign function or imported with a a static address import like

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

IArray UArray (FunPtr a) 

Methods

bounds :: Ix i => UArray i (FunPtr a) -> (i, i) #

numElements :: Ix i => UArray i (FunPtr a) -> Int

unsafeArray :: Ix i => (i, i) -> [(Int, FunPtr a)] -> UArray i (FunPtr a)

unsafeAt :: Ix i => UArray i (FunPtr a) -> Int -> FunPtr a

unsafeReplace :: Ix i => UArray i (FunPtr a) -> [(Int, FunPtr a)] -> UArray i (FunPtr a)

unsafeAccum :: Ix i => (FunPtr a -> e' -> FunPtr a) -> UArray i (FunPtr a) -> [(Int, e')] -> UArray i (FunPtr a)

unsafeAccumArray :: Ix i => (FunPtr a -> e' -> FunPtr a) -> FunPtr a -> (i, i) -> [(Int, e')] -> UArray i (FunPtr a)

Eq (FunPtr a) 

Methods

(==) :: FunPtr a -> FunPtr a -> Bool #

(/=) :: FunPtr a -> FunPtr a -> Bool #

Ord (FunPtr a) 

Methods

compare :: FunPtr a -> FunPtr a -> Ordering #

(<) :: FunPtr a -> FunPtr a -> Bool #

(<=) :: FunPtr a -> FunPtr a -> Bool #

(>) :: FunPtr a -> FunPtr a -> Bool #

(>=) :: FunPtr a -> FunPtr a -> Bool #

max :: FunPtr a -> FunPtr a -> FunPtr a #

min :: FunPtr a -> FunPtr a -> FunPtr a #

Show (FunPtr a) 

Methods

showsPrec :: Int -> FunPtr a -> ShowS #

show :: FunPtr a -> String #

showList :: [FunPtr a] -> ShowS #

Storable (FunPtr a) 

Methods

sizeOf :: FunPtr a -> Int #

alignment :: FunPtr a -> Int #

peekElemOff :: Ptr (FunPtr a) -> Int -> IO (FunPtr a) #

pokeElemOff :: Ptr (FunPtr a) -> Int -> FunPtr a -> IO () #

peekByteOff :: Ptr b -> Int -> IO (FunPtr a) #

pokeByteOff :: Ptr b -> Int -> FunPtr a -> IO () #

peek :: Ptr (FunPtr a) -> IO (FunPtr a) #

poke :: Ptr (FunPtr a) -> FunPtr a -> IO () #

Hashable (FunPtr a) 

Methods

hashWithSalt :: Int -> FunPtr a -> Int #

hash :: FunPtr a -> Int #

MArray (STUArray s) (FunPtr a) (ST s) 

Methods

getBounds :: Ix i => STUArray s i (FunPtr a) -> ST s (i, i) #

getNumElements :: Ix i => STUArray s i (FunPtr a) -> ST s Int

newArray :: Ix i => (i, i) -> FunPtr a -> ST s (STUArray s i (FunPtr a)) #

newArray_ :: Ix i => (i, i) -> ST s (STUArray s i (FunPtr a)) #

unsafeNewArray_ :: Ix i => (i, i) -> ST s (STUArray s i (FunPtr a))

unsafeRead :: Ix i => STUArray s i (FunPtr a) -> Int -> ST s (FunPtr a)

unsafeWrite :: Ix i => STUArray s i (FunPtr a) -> Int -> FunPtr a -> ST s ()

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 #

Casts a Ptr to a FunPtr.

Note: this is valid only on architectures where data and function pointers range over the same set of addresses, and should only be used for bindings to external libraries whose interface already relies on this assumption.

castFunPtrToPtr :: FunPtr a -> Ptr b #

Casts a FunPtr to a Ptr.

Note: this is valid only on architectures where data and function pointers range over the same set of addresses, and should only be used for bindings to external libraries whose interface already relies on this assumption.

Pointer as a Word

data WordPtr :: * #

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

Bounded WordPtr 
Enum WordPtr 
Eq WordPtr 

Methods

(==) :: WordPtr -> WordPtr -> Bool #

(/=) :: WordPtr -> WordPtr -> Bool #

Integral WordPtr 
Num WordPtr 
Ord WordPtr 
Read WordPtr 
Real WordPtr 
Show WordPtr 
Storable WordPtr 
Bits WordPtr 
FiniteBits WordPtr 
Hashable WordPtr 

Methods

hashWithSalt :: Int -> WordPtr -> Int #

hash :: WordPtr -> Int #

Buildable WordPtr 

Methods

build :: WordPtr -> Builder #

Storable WordPtr Source # 

wordPtrToPtr :: WordPtr -> Ptr a #

casts a WordPtr to a Ptr

ptrToWordPtr :: Ptr a -> WordPtr #

casts a Ptr to a WordPtr