The module Data.Storable provides an extension to the Foreign.Storable type class adding support for variable-sized data types.
The member functions of this class facilitate writing values of arbitrary (including recursive) data types to raw memory and reading values from blocks of raw memory. The class, furthermore, includes support for computing the storage requirements and alignment restrictions of storable types.
This class fills the gap between Foreign.Storable and Data.Binary. It adds support for marshalling (finite) values of variable-sized data types, like lists or trees, while preserving the performance and memory efficiency one expects from the Storable class. It also provides a (monadic) syntactic sugar that takes care of alignment restrictions by itself and makes instance deriving easy.
The primary aim of this class, as opposed to Foreign.Storable, is storing values to raw memory for the purpose of sending them over a network (in a homogeneous distributed environment, no endianness translation is done) or dumping them to external storage. It was not intended to be used for marshalling structures to/from C, although it may be used for that -- you'll need, however, specially crafted instances for compound data types that apply alignment restrictions recursively, not only for elementary Storable values. These may be provided someday.
For help on deriving instances see the source of the
Data.Storable.Instances module. For help on usage of the
Ptr type, which
represents raw memory addresses, see the documentation of Foreign Function
Computes the storage requirements (in bytes) of the argument. The value of the argument _is_ used.
Computes the alignment constraint of the argument. An alignment
x is fulfilled by any address divisible by
The value of the argument _is_not_ used.
Read a value from the given memory location.
Note that the peekV and pokeV functions might require properly aligned
addresses to function correctly. This is architecture dependent; thus,
portable code should ensure that when peeking or poking values of some
a, the alignment constraint for
a, as given by the function
alignmentV is fulfilled.