haskus-binary-1.4: Haskus binary format manipulation

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

castPtr, 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

(-->) :: forall path l. KnownNat (LPathOffset path l) => p l -> path -> p (LPathType path l) Source #

Add offset to the given layout field

Instances
PtrLike Ptr Source # 
Instance details

Defined in Haskus.Format.Binary.Ptr

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 #

(-->) :: KnownNat (LPathOffset path l) => Ptr l -> path -> Ptr (LPathType path l) Source #

PtrLike FinalizedPtr Source # 
Instance details

Defined in Haskus.Format.Binary.Ptr

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 # 
Instance details

Defined in Haskus.Format.Binary.Ptr

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 #

(-->) :: KnownNat (LPathOffset path l) => Ptr l -> path -> Ptr (LPathType path l) Source #

Generic1 (URec (Ptr ()) :: k -> Type) 
Instance details

Defined in GHC.Generics

Associated Types

type Rep1 (URec (Ptr ())) :: k -> Type #

Methods

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

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

Eq (Ptr a)

Since: base-2.1

Instance details

Defined in GHC.Ptr

Methods

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

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

Data a => Data (Ptr a)

Since: base-4.8.0.0

Instance details

Defined in Data.Data

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

Ord (Ptr a)

Since: base-2.1

Instance details

Defined in GHC.Ptr

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)

Since: base-2.1

Instance details

Defined in GHC.Ptr

Methods

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

show :: Ptr a -> String #

showList :: [Ptr a] -> ShowS #

Storable (Ptr a)

Since: base-2.1

Instance details

Defined in Foreign.Storable

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

Prim (Ptr a) 
Instance details

Defined in Data.Primitive.Types

Storable (Ptr a) Source # 
Instance details

Defined in Haskus.Format.Binary.Storable

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 #

Functor (URec (Ptr ()) :: Type -> Type)

Since: base-4.9.0.0

Instance details

Defined in GHC.Generics

Methods

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

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

Foldable (URec (Ptr ()) :: Type -> Type)

Since: base-4.9.0.0

Instance details

Defined in Data.Foldable

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 ()) :: Type -> Type)

Since: base-4.9.0.0

Instance details

Defined in Data.Traversable

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

Eq (URec (Ptr ()) p)

Since: base-4.9.0.0

Instance details

Defined in GHC.Generics

Methods

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

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

Ord (URec (Ptr ()) p)

Since: base-4.9.0.0

Instance details

Defined in GHC.Generics

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) 
Instance details

Defined in GHC.Generics

Associated Types

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

Methods

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

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

data URec (Ptr ()) (p :: k)

Used for marking occurrences of Addr#

Since: base-4.9.0.0

Instance details

Defined in GHC.Generics

data URec (Ptr ()) (p :: k) = UAddr {}
type Rep1 (URec (Ptr ()) :: k -> Type)

Since: base-4.9.0.0

Instance details

Defined in GHC.Generics

type Rep1 (URec (Ptr ()) :: k -> Type) = D1 (MetaData "URec" "GHC.Generics" "base" False) (C1 (MetaCons "UAddr" PrefixI True) (S1 (MetaSel (Just "uAddr#") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (UAddr :: k -> Type)))
type Rep (URec (Ptr ()) p)

Since: base-4.9.0.0

Instance details

Defined in GHC.Generics

type Rep (URec (Ptr ()) p) = D1 (MetaData "URec" "GHC.Generics" "base" False) (C1 (MetaCons "UAddr" PrefixI True) (S1 (MetaSel (Just "uAddr#") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (UAddr :: Type -> Type)))

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)

Since: base-2.1

Instance details

Defined in GHC.ForeignPtr

Methods

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

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

Data a => Data (ForeignPtr a)

Since: base-4.8.0.0

Instance details

Defined in Data.Data

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)

Since: base-2.1

Instance details

Defined in GHC.ForeignPtr

Show (ForeignPtr a)

Since: base-2.1

Instance details

Defined in GHC.ForeignPtr

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
Eq (FunPtr a) 
Instance details

Defined in GHC.Ptr

Methods

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

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

Ord (FunPtr a) 
Instance details

Defined in GHC.Ptr

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)

Since: base-2.1

Instance details

Defined in GHC.Ptr

Methods

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

show :: FunPtr a -> String #

showList :: [FunPtr a] -> ShowS #

Storable (FunPtr a)

Since: base-2.1

Instance details

Defined in Foreign.Storable

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

Prim (FunPtr a) 
Instance details

Defined in Data.Primitive.Types

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 
Instance details

Defined in Foreign.Ptr

Enum WordPtr 
Instance details

Defined in Foreign.Ptr

Eq WordPtr 
Instance details

Defined in Foreign.Ptr

Methods

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

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

Integral WordPtr 
Instance details

Defined in Foreign.Ptr

Data WordPtr

Since: base-4.11.0.0

Instance details

Defined in Data.Data

Methods

gfoldl :: (forall d b. Data d => c (d -> b) -> d -> c b) -> (forall g. g -> c g) -> WordPtr -> c WordPtr #

gunfold :: (forall b r. Data b => c (b -> r) -> c r) -> (forall r. r -> c r) -> Constr -> c WordPtr #

toConstr :: WordPtr -> Constr #

dataTypeOf :: WordPtr -> DataType #

dataCast1 :: Typeable t => (forall d. Data d => c (t d)) -> Maybe (c WordPtr) #

dataCast2 :: Typeable t => (forall d e. (Data d, Data e) => c (t d e)) -> Maybe (c WordPtr) #

gmapT :: (forall b. Data b => b -> b) -> WordPtr -> WordPtr #

gmapQl :: (r -> r' -> r) -> r -> (forall d. Data d => d -> r') -> WordPtr -> r #

gmapQr :: (r' -> r -> r) -> r -> (forall d. Data d => d -> r') -> WordPtr -> r #

gmapQ :: (forall d. Data d => d -> u) -> WordPtr -> [u] #

gmapQi :: Int -> (forall d. Data d => d -> u) -> WordPtr -> u #

gmapM :: Monad m => (forall d. Data d => d -> m d) -> WordPtr -> m WordPtr #

gmapMp :: MonadPlus m => (forall d. Data d => d -> m d) -> WordPtr -> m WordPtr #

gmapMo :: MonadPlus m => (forall d. Data d => d -> m d) -> WordPtr -> m WordPtr #

Num WordPtr 
Instance details

Defined in Foreign.Ptr

Ord WordPtr 
Instance details

Defined in Foreign.Ptr

Read WordPtr 
Instance details

Defined in Foreign.Ptr

Real WordPtr 
Instance details

Defined in Foreign.Ptr

Show WordPtr 
Instance details

Defined in Foreign.Ptr

Storable WordPtr 
Instance details

Defined in Foreign.Ptr

Bits WordPtr 
Instance details

Defined in Foreign.Ptr

FiniteBits WordPtr 
Instance details

Defined in Foreign.Ptr

Storable WordPtr Source # 
Instance details

Defined in Haskus.Format.Binary.Storable

wordPtrToPtr :: WordPtr -> Ptr a #

casts a WordPtr to a Ptr

ptrToWordPtr :: Ptr a -> WordPtr #

casts a Ptr to a WordPtr