| Safe Haskell | Safe-Inferred |
|---|---|
| Language | GHC2021 |
HsBindgen.Runtime.Marshal
Contents
Description
Marshaling and serialization
Generalizes Storable. For details, see
https://github.com/well-typed/hs-bindgen/issues/649.
This module is intended to be imported qualified.
import HsBindgen.Runtime.Prelude import HsBindgen.Runtime.Marshal qualified as Marshal
Synopsis
- class StaticSize a where
- staticSizeOf :: Proxy a -> Int
- staticAlignment :: Proxy a -> Int
- class ReadRaw a where
- class WriteRaw a where
- newtype EquivStorable a = EquivStorable a
- readRawByteOff :: ReadRaw a => Ptr b -> Int -> IO a
- writeRawByteOff :: WriteRaw a => Ptr b -> Int -> a -> IO ()
- readRawElemOff :: forall a. (ReadRaw a, StaticSize a) => Ptr a -> Int -> IO a
- writeRawElemOff :: forall a. (StaticSize a, WriteRaw a) => Ptr a -> Int -> a -> IO ()
- maybeReadRaw :: ReadRaw a => Ptr a -> IO (Maybe a)
- with :: forall a b. (StaticSize a, WriteRaw a) => a -> (Ptr a -> IO b) -> IO b
- withZero :: forall a b. (StaticSize a, WriteRaw a) => a -> (Ptr a -> IO b) -> IO b
- new :: forall a. (StaticSize a, WriteRaw a) => a -> IO (ForeignPtr a)
- newZero :: forall a. (StaticSize a, WriteRaw a) => a -> IO (ForeignPtr a)
Type Classes
class StaticSize a where Source #
Size and alignment for values that have a static size in memory
Types that are instances of Storable can derive this instance.
Minimal complete definition
Nothing
Methods
staticSizeOf :: Proxy a -> Int Source #
Storage requirements (bytes)
staticAlignment :: Proxy a -> Int Source #
Alignment (bytes)
Instances
class ReadRaw a where Source #
Values that can be read from memory
Types that are instances of Storable can derive this instance.
Minimal complete definition
Nothing
Methods
readRaw :: Ptr a -> IO a Source #
Read a value from the given memory location
This function might require a properly aligned address to function correctly, depending on the architecture.
Instances
class WriteRaw a where Source #
Values that can be written to memory
Types that are instances of Storable can derive this instance.
Minimal complete definition
Nothing
Methods
writeRaw :: Ptr a -> a -> IO () Source #
Write a value to the given memory location
This function might require a properly aligned address to function correctly, depending on the architecture.
Instances
newtype EquivStorable a Source #
Type used to derive a Storable instance when the type has StaticSize,
ReadRaw, and WriteRaw instances
Use the DerivingVia GHC extension as follows:
{-# LANGUAGE DerivingVia #-}
data Foo = Foo { ... }
deriving Storable via EquivStorable Foo
Constructors
| EquivStorable a |
Instances
| (ReadRaw a, StaticSize a, WriteRaw a) => Storable (EquivStorable a) Source # | |
Defined in HsBindgen.Runtime.Marshal Methods sizeOf :: EquivStorable a -> Int # alignment :: EquivStorable a -> Int # peekElemOff :: Ptr (EquivStorable a) -> Int -> IO (EquivStorable a) # pokeElemOff :: Ptr (EquivStorable a) -> Int -> EquivStorable a -> IO () # peekByteOff :: Ptr b -> Int -> IO (EquivStorable a) # pokeByteOff :: Ptr b -> Int -> EquivStorable a -> IO () # peek :: Ptr (EquivStorable a) -> IO (EquivStorable a) # poke :: Ptr (EquivStorable a) -> EquivStorable a -> IO () # | |
Utility Functions
readRawByteOff :: ReadRaw a => Ptr b -> Int -> IO a Source #
Read a value from the given memory location, given by a base address and an offset
writeRawByteOff :: WriteRaw a => Ptr b -> Int -> a -> IO () Source #
Write a value to the given memory location, given by a base address and an offset
readRawElemOff :: forall a. (ReadRaw a, StaticSize a) => Ptr a -> Int -> IO a Source #
Read a value from a memory area regarded as an array of values of the same kind
The first argument specifies the start address of the array. The second specifies the (zero-based) index into the array.
writeRawElemOff :: forall a. (StaticSize a, WriteRaw a) => Ptr a -> Int -> a -> IO () Source #
Write a value to a memory area regarded as an array of values of the same kind
The first argument specifies the start address of the array. The second specifies the (zero-based) index into the array.
maybeReadRaw :: ReadRaw a => Ptr a -> IO (Maybe a) Source #
Read a value from memory when passed a non-null pointer
with :: forall a b. (StaticSize a, WriteRaw a) => a -> (Ptr a -> IO b) -> IO b Source #
Allocate local memory, write the specified value, and call a function with the pointer
The allocated memory is aligned.
Memory that is not written to by poke may contain arbitrary data.
The allocated memory is freed when the function terminates, either normally or via an exception. The passed pointer must therefore not be used after this.
withZero :: forall a b. (StaticSize a, WriteRaw a) => a -> (Ptr a -> IO b) -> IO b Source #
Allocate local memory, write the specified value, and call a function with the pointer
The allocated memory is aligned.
The memory is filled with bytes of value zero before the value is written.
Memory that is not written to by poke contains zeros, not arbitrary data.
The allocated memory is freed when the function terminates, either normally or via an exception. The passed pointer must therefore not be used after this.
new :: forall a. (StaticSize a, WriteRaw a) => a -> IO (ForeignPtr a) Source #
Allocate memory, write the specified value, and the ForeignPtr
The allocated memory is aligned.
Memory that is not written to by writeRaw may contain arbitrary data.
newZero :: forall a. (StaticSize a, WriteRaw a) => a -> IO (ForeignPtr a) Source #
Allocate memory, write the specified value, and the ForeignPtr
The allocated memory is aligned.
The memory is filled with bytes of value zero before the value is written.
Memory that is not written to by writeRaw contains zeros, not arbitrary
data.