Data.Capnp.Address

This module provides facilities for manipulating raw addresses within Cap'N Proto messages.

This is a low level module that very few users will need to use directly.

Documentation

data WordAddr

The address of a word within a message

Constructors

WordAt

Fields

• segIndex :: !Int

  Segment number

• wordIndex :: !WordCount

  offset in words from the start of the segment.

Instances

Eq WordAddr

Defined in Data.Capnp.Address

Methods

(==) :: WordAddr -> WordAddr -> Bool

(/=) :: WordAddr -> WordAddr -> Bool

Show WordAddr

Defined in Data.Capnp.Address

Methods

showsPrec :: Int -> WordAddr -> ShowS

show :: WordAddr -> String

showList :: [WordAddr] -> ShowS

newtype CapAddr

The "address" of a capability

Constructors

Cap Word32

Instances

Eq CapAddr

Defined in Data.Capnp.Address

Methods

(==) :: CapAddr -> CapAddr -> Bool

(/=) :: CapAddr -> CapAddr -> Bool

Show CapAddr

Defined in Data.Capnp.Address

Methods

showsPrec :: Int -> CapAddr -> ShowS

show :: CapAddr -> String

showList :: [CapAddr] -> ShowS

data Addr

An address, i.e. a location that a pointer may point at.

Constructors

WordAddr !WordAddr

The address of some data in the message.

CapAddr !CapAddr

The "address" of a capability.

Instances

Eq Addr

Defined in Data.Capnp.Address

Methods

(==) :: Addr -> Addr -> Bool

(/=) :: Addr -> Addr -> Bool

Show Addr

Defined in Data.Capnp.Address

Methods

showsPrec :: Int -> Addr -> ShowS

show :: Addr -> String

showList :: [Addr] -> ShowS

data OffsetError

An error returned by computeOffset; this describes the reason why a value cannot be directly addressed from a given location.

Constructors

DifferentSegments

The pointer and the value are in different segments.

OutOfRange

The pointer is in the correct segment, but too far away to encode the offset. (more than 30 bits would be required). This can only happen with segments that are > 8 GiB, which this library refuses to either decode or generate, so this should not come up in practice.

computeOffset :: WordAddr -> WordAddr -> Either OffsetError WordCount

computeOffset ptrAddr valueAddr computes the offset that should be stored in a struct or list pointer located at ptrAddr, in order to point at a value located at valueAddr. If the value cannot be directly addressed by a pointer at ptrAddr, then this returns Left, with the OffsetError describing the problem.

pointerFrom :: WordAddr -> WordAddr -> Ptr -> Either OffsetError Ptr

pointerFrom ptrAddr targetAddr ptr updates ptr, such that it is correct to target a value located at targetAddr given that the pointer itself is located at ptrAddr. Returns Left if this is not possible.

It is illegal to call this on a capability pointer.

For far pointers, targetAddr is taken to be the address of the landing pad, rather than the final value.

resolvePtr :: WordAddr -> Ptr -> Addr

resolvePtr from ptr resolves the pointer ptr to an address relative to from. Note that inter-segment pointers (FarPtr) resolve to the address of the landing pad, *not* the the final address of the object pointed to, as the latter would reqiure access to the message.