Data.Storable

The module Data.Storable provides an extension to the Foreign.Storable type class adding support for variable-sized data types.

Documentation

class StorableM a where

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.

The API used for writing/reading values is provided by the sizeOfV, alignmentV, peekV and pokeV functions (V standing for value).

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 Interface (FFI).

Minimal complete definition: sizeOfM, alignmentM, peekM and pokeM.

Methods

sizeOfM :: a -> SizeOf ()

alignmentM :: a -> Alignment ()

peekM :: Offset a

pokeM :: a -> Offset ()

Instances

Storable a => StorableM a

StorableM a => StorableM [a]

(StorableM a, StorableM b) => StorableM (a, b)

sizeOfV :: StorableM a => a -> Int

Computes the storage requirements (in bytes) of the argument. The value of the argument _is_ used.

alignmentV :: StorableM a => a -> Int

Computes the alignment constraint of the argument. An alignment constraint x is fulfilled by any address divisible by x. The value of the argument _is_not_ used.

peekV :: StorableM a => Ptr a -> IO a

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 type a, the alignment constraint for a, as given by the function alignmentV is fulfilled.

pokeV :: StorableM a => Ptr a -> a -> IO ()

Write the given value to the given memory location. Alignment restrictions might apply; see peekV.