Data.Prim.Memory.ForeignPtr

Documentation

class PtrAccess s p where

For memory allocated as pinned it is possible to operate on it with a Ptr. Any data type that is backed by such memory can have a PtrAccess instance. The simplest way is to convert it to a ForeignPtr and other functions will come for free.

Minimal complete definition

toForeignPtr

Methods

toForeignPtr :: MonadPrim s m => p -> m (ForeignPtr a)

Convert to ForeignPtr.

withPtrAccess :: MonadPrim s m => p -> (Ptr a -> m b) -> m b

Apply an action to the raw memory Ptr to which the data type point to. Type of data stored in memory is left ambiguous intentionaly, so that the user can choose how to treat the memory content.

withNoHaltPtrAccess :: MonadUnliftPrim s m => p -> (Ptr a -> m b) -> m b

See this GHC issue #18061 and related to get more insight why this is needed.

Instances

PtrAccess s ByteString

Read-only access, but it is not enforced.

Defined in Data.Prim.Memory.ForeignPtr

Methods

toForeignPtr :: MonadPrim s m => ByteString -> m (ForeignPtr a)

withPtrAccess :: MonadPrim s m => ByteString -> (Ptr a -> m b) -> m b

withNoHaltPtrAccess :: MonadUnliftPrim s m => ByteString -> (Ptr a -> m b) -> m b

PtrAccess s (Bytes Pin)

Read-only access, but it is not enforced.

Defined in Data.Prim.Memory.ForeignPtr

Methods

toForeignPtr :: MonadPrim s m => Bytes Pin -> m (ForeignPtr a)

withPtrAccess :: MonadPrim s m => Bytes Pin -> (Ptr a -> m b) -> m b

withNoHaltPtrAccess :: MonadUnliftPrim s m => Bytes Pin -> (Ptr a -> m b) -> m b

PtrAccess s (MByteString s)

Defined in Data.Prim.Memory.ForeignPtr

Methods

toForeignPtr :: MonadPrim s m => MByteString s -> m (ForeignPtr a)

withPtrAccess :: MonadPrim s m => MByteString s -> (Ptr a -> m b) -> m b

withNoHaltPtrAccess :: MonadUnliftPrim s m => MByteString s -> (Ptr a -> m b) -> m b

PtrAccess s (ForeignPtr a)

Defined in Data.Prim.Memory.ForeignPtr

Methods

toForeignPtr :: MonadPrim s m => ForeignPtr a -> m (ForeignPtr a0)

withPtrAccess :: MonadPrim s m => ForeignPtr a -> (Ptr a0 -> m b) -> m b

withNoHaltPtrAccess :: MonadUnliftPrim s m => ForeignPtr a -> (Ptr a0 -> m b) -> m b

PtrAccess s (Addr e)

Read-only access, but it is not enforced.

Defined in Data.Prim.Memory.Addr

Methods

toForeignPtr :: MonadPrim s m => Addr e -> m (ForeignPtr a)

withPtrAccess :: MonadPrim s m => Addr e -> (Ptr a -> m b) -> m b

withNoHaltPtrAccess :: MonadUnliftPrim s m => Addr e -> (Ptr a -> m b) -> m b

PtrAccess s (MBytes Pin s)

Defined in Data.Prim.Memory.ForeignPtr

Methods

toForeignPtr :: MonadPrim s m => MBytes Pin s -> m (ForeignPtr a)

withPtrAccess :: MonadPrim s m => MBytes Pin s -> (Ptr a -> m b) -> m b

withNoHaltPtrAccess :: MonadUnliftPrim s m => MBytes Pin s -> (Ptr a -> m b) -> m b

PtrAccess s (ByteArray Pin e)

Read-only access, but it is not enforced.

Defined in Data.Prim.Memory.ByteArray

Methods

toForeignPtr :: MonadPrim s m => ByteArray Pin e -> m (ForeignPtr a)

withPtrAccess :: MonadPrim s m => ByteArray Pin e -> (Ptr a -> m b) -> m b

withNoHaltPtrAccess :: MonadUnliftPrim s m => ByteArray Pin e -> (Ptr a -> m b) -> m b

PtrAccess s (MAddr e s)

Defined in Data.Prim.Memory.Addr

Methods

toForeignPtr :: MonadPrim s m => MAddr e s -> m (ForeignPtr a)

withPtrAccess :: MonadPrim s m => MAddr e s -> (Ptr a -> m b) -> m b

withNoHaltPtrAccess :: MonadUnliftPrim s m => MAddr e s -> (Ptr a -> m b) -> m b

PtrAccess s (MByteArray Pin e s)

Defined in Data.Prim.Memory.ByteArray

Methods

toForeignPtr :: MonadPrim s m => MByteArray Pin e s -> m (ForeignPtr a)

withPtrAccess :: MonadPrim s m => MByteArray Pin e s -> (Ptr a -> m b) -> m b

withNoHaltPtrAccess :: MonadUnliftPrim s m => MByteArray Pin e s -> (Ptr a -> m b) -> m b

ForeignPtr

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.

Constructors

ForeignPtr Addr# ForeignPtrContents

Instances

PtrAccess s (ForeignPtr a)

Defined in Data.Prim.Memory.ForeignPtr

Methods

toForeignPtr :: MonadPrim s m => ForeignPtr a -> m (ForeignPtr a0)

withPtrAccess :: MonadPrim s m => ForeignPtr a -> (Ptr a0 -> m b) -> m b

withNoHaltPtrAccess :: MonadUnliftPrim s m => ForeignPtr a -> (Ptr a0 -> m b) -> m b

Eq (ForeignPtr a)

Since: base-2.1

Defined in GHC.ForeignPtr

Methods

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

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

Ord (ForeignPtr a)

Since: base-2.1

Defined in GHC.ForeignPtr

Methods

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

Methods

showsPrec :: Int -> ForeignPtr a -> ShowS

show :: ForeignPtr a -> String

showList :: [ForeignPtr a] -> ShowS

MemWrite (MemState (ForeignPtr a))

Defined in Data.Prim.Memory.Internal

Methods

readOffMem :: (MonadPrim s m, Prim e) => MemState (ForeignPtr a) s -> Off e -> m e

readByteOffMem :: (MonadPrim s m, Prim e) => MemState (ForeignPtr a) s -> Off Word8 -> m e

writeOffMem :: (MonadPrim s m, Prim e) => MemState (ForeignPtr a) s -> Off e -> e -> m ()

writeByteOffMem :: (MonadPrim s m, Prim e) => MemState (ForeignPtr a) s -> Off Word8 -> e -> m ()

moveByteOffToMBytesMem :: (MonadPrim s m, Prim e) => MemState (ForeignPtr a) s -> Off Word8 -> MBytes p s -> Off Word8 -> Count e -> m ()

moveByteOffToPtrMem :: (MonadPrim s m, Prim e) => MemState (ForeignPtr a) s -> Off Word8 -> Ptr e -> Off Word8 -> Count e -> m ()

copyByteOffMem :: (MonadPrim s m, MemRead r, Prim e) => r -> Off Word8 -> MemState (ForeignPtr a) s -> Off Word8 -> Count e -> m ()

moveByteOffMem :: (MonadPrim s m, MemWrite w', Prim e) => w' s -> Off Word8 -> MemState (ForeignPtr a) s -> Off Word8 -> Count e -> m ()

setMem :: (MonadPrim s m, Prim e) => MemState (ForeignPtr a) s -> Off e -> Count e -> e -> m ()

castForeignPtr :: ForeignPtr a -> ForeignPtr b

This function casts a ForeignPtr parameterised by one type into another type.

unsafeForeignPtrToPtr :: ForeignPtr a -> Ptr a

This function extracts the pointer component of a foreign pointer. This is a potentially dangerous operations, as if the argument to unsafeForeignPtrToPtr is the last usage occurrence of the given foreign pointer, then its finalizer(s) will be run, which potentially invalidates the plain pointer just obtained. Hence, touchForeignPtr must be used wherever it has to be guaranteed that the pointer lives on - i.e., has another usage occurrence.

To avoid subtle coding errors, hand written marshalling code should preferably use withForeignPtr rather than combinations of unsafeForeignPtrToPtr and touchForeignPtr. However, the latter routines are occasionally preferred in tool generated marshalling code.

data ForeignPtrContents

Constructors

PlainForeignPtr !(IORef Finalizers)

MallocPtr (MutableByteArray# RealWorld) !(IORef Finalizers)

PlainPtr (MutableByteArray# RealWorld)

Pointer arithmetic

plusOffForeignPtr :: Prim e => ForeignPtr e -> Off e -> ForeignPtr e

Advances the given address by the given offset in number of elemeents. This operation does not affect associated finalizers in any way.

Since: 0.1.0

plusByteOffForeignPtr :: ForeignPtr e -> Off Word8 -> ForeignPtr e

Advances the given address by the given offset in bytes. This operation does not affect associated finalizers in any way.

Since: 0.1.0

minusOffForeignPtr :: Prim e => ForeignPtr e -> ForeignPtr e -> Off e

Find the offset in number of elements that is between the two pointers by subtracting one address from another and dividing the result by the size of an element.

Since: 0.1.0

minusOffRemForeignPtr :: Prim e => ForeignPtr e -> ForeignPtr e -> (Off e, Off Word8)

Same as minusOffForeignPtr, but will also return the remainder in bytes that is left over.

Since: 0.1.0

minusByteOffForeignPtr :: ForeignPtr e -> ForeignPtr e -> Off Word8

Find the offset in bytes that is between the two pointers by subtracting one address from another.

Since: 0.1.0

withForeignPtr :: MonadPrim s m => ForeignPtr e -> (Ptr e -> m b) -> m b

Apply an action to the raw pointer. It is unsafe to return the actual pointer back from the action because memory itself might get garbage collected or cleaned up by finalizers.

It is also important not to run non-terminating actions, because GHC can optimize away the logic that runs after the action and GC will happen before the action get's a chance to finish resulting in corrupt memory. Whenever you have an action that runs an infinite loop or ends in an exception throwing, make sure to use withNoHaltForeignPtr instead.

withNoHaltForeignPtr :: MonadUnliftPrim s m => ForeignPtr e -> (Ptr e -> m b) -> m b

Same thing as withForeignPtr except it should be used for never ending actions. See withNoHaltPtrAccess for more information on how this differes from withForeignPtr.

Since: 0.1.0

PlainPtr

mallocPlainForeignPtr :: forall e m s. (MonadPrim s m, Prim e) => m (ForeignPtr e)

Similar to mallocPlainForeignPtr, except instead of Storable we use Prim and we are not restricted to IO, since finalizers are not possible with PlaintPtr

mallocCountPlainForeignPtr :: (MonadPrim s m, Prim e) => Count e -> m (ForeignPtr e)

Similar to mallocPlainForeignPtrArray, except instead of Storable we use Prim.

mallocCountPlainForeignPtrAligned :: forall e m s. (MonadPrim s m, Prim e) => Count e -> m (ForeignPtr e)

Just like mallocCountForeignPtr, but memory is also aligned according to Prim instance

mallocByteCountPlainForeignPtr :: MonadPrim s m => Count Word8 -> m (ForeignPtr e)

Lifted version of mallocForeignPtrBytes.

mallocByteCountPlainForeignPtrAligned

Arguments

:: MonadPrim s m

=> Count Word8

Number of bytes to allocate

-> Int

Alignment in bytes

-> m (ForeignPtr e)

Lifted version of mallocForeignPtrAlignedBytes.

With Finalizers

finalizeForeignPtr :: MonadPrim RW m => ForeignPtr e -> m ()

Lifted version of finalizeForeignPtr.

Foreign finalizer

type FinalizerPtr a = FunPtr (Ptr a -> IO ())

A finalizer is represented as a pointer to a foreign function that, at finalisation time, gets as an argument a plain pointer variant of the foreign pointer that the finalizer is associated with.

Note that the foreign function must use the ccall calling convention.

newForeignPtr :: MonadPrim RW m => FinalizerPtr e -> Ptr e -> m (ForeignPtr e)

Lifted version of newForeignPtr.

newForeignPtr_ :: MonadPrim RW m => Ptr e -> m (ForeignPtr e)

Lifted version of newForeignPtr_.

touchForeignPtr :: MonadPrim s m => ForeignPtr e -> m ()

Lifted version of touchForeignPtr.

mallocForeignPtr :: forall e m. (MonadPrim RW m, Prim e) => m (ForeignPtr e)

Simila to mallocForeignPtr, except it operates on Prim, instead of Storable.

mallocCountForeignPtr :: (MonadPrim RW m, Prim e) => Count e -> m (ForeignPtr e)

Similar to mallocForeignPtrArray, except instead of Storable we use Prim.

mallocCountForeignPtrAligned :: (MonadPrim RW m, Prim e) => Count e -> m (ForeignPtr e)

Just like mallocCountForeignPtr, but memory is also aligned according to Prim instance

mallocByteCountForeignPtr :: MonadPrim RW m => Count Word8 -> m (ForeignPtr e)

Lifted version of mallocForeignPtrBytes.

mallocByteCountForeignPtrAligned

Arguments

:: MonadPrim RW m

=> Count Word8

Number of bytes to allocate

-> Int

Alignment in bytes

-> m (ForeignPtr e)

Lifted version of mallocForeignPtrAlignedBytes.

addForeignPtrFinalizer :: MonadPrim RW m => FinalizerPtr e -> ForeignPtr e -> m ()

Lifted version of addForeignPtrFinalizer

With environment

type FinalizerEnvPtr env a = FunPtr (Ptr env -> Ptr a -> IO ())

newForeignPtrEnv :: MonadPrim RW m => FinalizerEnvPtr env e -> Ptr env -> Ptr e -> m (ForeignPtr e)

Lifted version of newForeignPtrEnv.

addForeignPtrFinalizerEnv :: MonadPrim RW m => FinalizerEnvPtr env e -> Ptr env -> ForeignPtr e -> m ()

Lifted version of addForeignPtrFinalizerEnv

Haskell finalizer

newConcForeignPtr :: MonadUnliftPrim RW m => Ptr e -> m () -> m (ForeignPtr e)

Unlifted version of newConcForeignPtr

addForeignPtrConcFinalizer :: MonadUnliftPrim RW m => ForeignPtr a -> m () -> m ()

Unlifted version of addForeignPtrConcFinalizer

Conversion

Bytes

toForeignPtrBytes :: Bytes Pin -> ForeignPtr e

toForeignPtrMBytes :: MBytes Pin s -> ForeignPtr e