regional-pointers-0.3: Regional memory pointers

MaintainerBas van Dijk <v.dijk.bas@gmail.com>

Foreign.Ptr.Region

Contents

Description

 

Synopsis

Regional pointers

data RegionalPtr α r Source

A regional handle to memory. This should provide a safer replacement for Foreign.Ptr.Ptr

Instances

Note that this module re-exports the Control.Monad.Trans.Region module from the regions package which allows you to:

  • Run a region using runRegionT.
  • Concurrently run a region inside another region using forkIOTopRegion.
  • Duplicate a RegionalPtr to a parent region using dup.

Constructing regional pointers

regionalPtr :: MonadIO pr => Ptr α -> CloseAction -> RegionT s pr (RegionalPtr α (RegionT s pr))Source

Construct a regional pointer from a native pointer and an IO computation that frees the pointer which is executed when the region exits.

nullPtr :: RegionalPtr α rSource

The constant nullPtr contains a distinguished value of RegionalPtr that is not associated with a valid memory location.

Note that nullPtr is a pure value. This means it does not perform the side-effect of registering a CloseAction like free nullPtr in the RegionT monad.

Pure functions on regional pointers

mapRegionalPtr :: (Ptr α -> Ptr β) -> RegionalPtr α r -> RegionalPtr β rSource

Apply a pure function to the inner pointer of a regional pointer.

castPtr :: RegionalPtr α r -> RegionalPtr β rSource

The castPtr function casts a pointer from one type to another.

Wraps: Foreign.Ptr.castPtr

plusPtr :: RegionalPtr α r -> Int -> RegionalPtr β rSource

Advances the given address by the given offset in bytes.

Wraps: Foreign.Ptr.plusPtr

alignPtr :: RegionalPtr α r -> Int -> RegionalPtr α rSource

Given an arbitrary address and an alignment constraint, alignPtr yields the next higher address that fulfills the alignment constraint. An alignment constraint x is fulfilled by any address divisible by x. This operation is idempotent.

Wraps: Foreign.Ptr.alignPtr

minusPtr :: RegionalPtr α r1 -> RegionalPtr β r2 -> IntSource

Computes the offset required to get from the second to the first argument. We have

 p2 == p1 `plusPtr` (p2 `minusPtr` p1)

Wraps: Foreign.Ptr.minusPtr