primitive-offset-0.2.0.1: Types for offsets into unboxed arrays
Safe HaskellSafe-Inferred
LanguageHaskell2010

Data.Primitive.PrimArray.Offset

Description

Data types for describing an array paired with an index into it. This is intended to be used in wrappers for unsafe FFI calls. For example, the POSIX function recvfrom takes a socklen_t* argument. (Let us assume that socklen_t is equivalant to int for this example.) How is this argument best described by a Haskell type? When working with pinned memory, the best option Ptr CInt. It works equally well regardless of whether we originally had an array of CInt or a pointer to a single CInt. This works because of functions like advancePtr and plusPtr that effectively index into an array. Unpinned memory, however, is trickier. We want to have the full flexibility (handling both a single-element or multi-element buffer) that Ptr CInt affords. We cannot offset into a MutablePrimArray to get a new one like we could with Ptr. (Such a function is not possible because unpinned memory can be relocated.) So, the offseting must be done in the C function wrapped by the unsafe FFI. This means that the offset must be passed together with the MutablePrimArray. This is the precisely the product that MutablePrimArrayOffset represents. In a type signature, it provides additional clarity about the meaning of the offset.

This library is used in the extensively in the posix-api library to clarify intent in a number of type signatures.

Synopsis

Types

data PrimArrayOffset a Source #

A primitive array and an index into the array.

Constructors

PrimArrayOffset 

Fields

data MutablePrimArrayOffset s a Source #

A mutable primitive array and an index into the array.

Constructors

MutablePrimArrayOffset 

Fields

Resolution

indexOffset :: Prim a => PrimArrayOffset a -> a Source #

Recover the element in the primitive array.

readOffset :: (PrimMonad m, Prim a) => MutablePrimArrayOffset (PrimState m) a -> m a Source #

Recover the element in the mutable primitive array.