Data.Primitive.PVar

Mutable variable with primitive value.

Synonym for RealWorld

Create a mutable variable in unpinned memory (i.e. GC can move it) with an initial value. This is a prefered way to create a mutable variable, since it will not contribute to memory fragmentation. For pinned memory versions see newPinnedPVar and newAlignedPinnedPVar

Run an ST action on a mutable variable.

Read a value from a mutable variable

Write a value into a mutable variable

Apply a pure function to the contents of a mutable variable. Returns the artifact of computation.

Apply a pure function to the contents of a mutable variable.

Apply a pure function to the contents of a mutable variable. Returns the old value.

Apply a pure function to the contents of a mutable variable. Returns the new value.

Apply a monadic action to the contents of a mutable variable. Returns the artifact of computation.

Apply a monadic action to the contents of a mutable variable.

Apply a monadic action to the contents of a mutable variable. Returns the old value.

Apply a monadic action to the contents of a mutable variable. Returns the new value.

Swap contents of two mutable variables.

Swap contents of two mutable variables. Returns their old values.

Copy contents of one mutable variable PVar into another

Size in bytes of a value stored inside the mutable variable. PVar itself is neither accessed nor evaluated.

Alignment in bytes of the value stored inside of the mutable variable. PVar itself is neither accessed nor evaluated.

Create a mutable variable in pinned memory with an initial value.

Create a mutable variable in pinned memory with an initial value and aligned according to its alignment

Apply an action to the Ptr that references the mutable variable, but only if it is backed by pinned memory, cause otherwise it would be unsafe.

Apply an action to the newly allocated PVar and to the Ptr that references it. Memory allocated with number of bytes specified by sizeOf a is allocated and pinned, therefore it is safe to operate directly with the pointer as well as over FFI. Returning the pointer from the supplied action would be very unsafe, therefore return the PVar if you still need it afterwards, garbage collector will cleanup the memory when it is no longer needed.

Same withStorablePVar, except memory is aligned according to alignment.

Copy contents of a mutable variable PVar into a pointer Ptr

Convert PVar into a ForeignPtr, but only if it is backed by pinned memory.

Check if PVar is backed by pinned memory or not

Use Storable reading functionality inside the PrimMonad.

Use Storable wrting functionality inside the PrimMonad.

Apply a function to an integer element of a PVar atomically. Implies a full memory barrier.

Apply a function to an integer element of a PVar atomically. Returns the old value. Implies a full memory barrier.

Apply a function to an integer element of a PVar atomically. Implies a full memory barrier. Returns the new value.

Apply a function to an integer element of a PVar atomically. Implies a full memory barrier. Returns the new value.

Read a value from PVar atomically. Implies a full memory barrier.

Write a value into an PVar atomically. Implies a full memory barrier.

Compare and swap. This is also a function that is used to implement atomicModifyIntPVar. Implies a full memory barrier.

Add two numbers, corresponds to (+) done atomically. Returns the previous value of the mutable variable. Implies a full memory barrier.

Subtract two numbers, corresponds to (-) done atomically. Returns the previous value of the mutable variable. Implies a full memory barrier.

Binary conjuction (AND), corresponds to (.&.) done atomically. Returns the previous value of the mutable variable. Implies a full memory barrier.

Binary negation of conjuction (NAND), corresponds to \x y -> complement (x .&. y) done atomically. Returns the previous value of the mutable variable. Implies a full memory barrier.

Binary disjunction (OR), corresponds to (.|.) done atomically. Returns the previous value of the mutable variable. Implies a full memory barrier.

Binary exclusive disjunction (XOR), corresponds to xor done atomically. Returns the previous value of the mutable variable. Implies a full memory barrier.

Binary negation (NOT), corresponds to ones' complement done atomically. Returns the previous value of the mutable variable. Implies a full memory barrier.

Class of types supporting primitive array operations. This includes interfacing with GC-managed memory (functions suffixed with ByteArray#) and interfacing with unmanaged memory (functions suffixed with Addr#). Endianness is platform-dependent.

PrimMonad's state token type can be annoying to handle in constraints. This typeclass lets users (visually) notice PrimState equality constraints less, by witnessing that s ~ PrimState m.

Class of monads which can perform primitive state-transformer actions.

RealWorld is deeply magical. It is primitive, but it is not unlifted (hence ptrArg). We never manipulate values of type RealWorld; it's only used in the type system, to parameterise State#.

The size of values of type a in bytes. The argument is not used.

It is recommended to use sizeOfType instead.

This function has existed since 0.1, but was moved from Data.Primitive to Data.Primitive.Types in version 0.6.3.0.

The alignment of values of type a in bytes. The argument is not used.

It is recommended to use alignmentOfType instead.

This function has existed since 0.1, but was moved from Data.Primitive to Data.Primitive.Types in version 0.6.3.0.

The strict ST monad. The ST monad allows for destructive updates, but is escapable (unlike IO). A computation of type ST s a returns a value of type a, and execute in "thread" s. The s parameter is either

• an uninstantiated type variable (inside invocations of runST), or

• RealWorld (inside invocations of stToIO).

It serves to keep the internal states of different invocations of runST separate from each other and from invocations of stToIO.

The >>= and >> operations are strict in the state (though not in values stored in the state). For example,

runST (writeSTRef _|_ v >>= f) = _|_

Return the value computed by a state thread. The forall ensures that the internal state used by the ST computation is inaccessible to the rest of the program.

The member functions of this class facilitate writing values of primitive types to raw memory (which may have been allocated with the above mentioned routines) and reading values from blocks of raw memory. The class, furthermore, includes support for computing the storage requirements and alignment restrictions of storable types.

Memory addresses are represented as values of type Ptr a, for some a which is an instance of class Storable. The type argument to Ptr helps provide some valuable type safety in FFI code (you can't mix pointers of different types without an explicit cast), while helping the Haskell type system figure out which marshalling method is needed for a given pointer.

All marshalling between Haskell and a foreign language ultimately boils down to translating Haskell data structures into the binary representation of a corresponding data structure of the foreign language and vice versa. To code this marshalling in Haskell, it is necessary to manipulate primitive data types stored in unstructured memory blocks. The class Storable facilitates this manipulation on all types for which it is instantiated, which are the standard basic types of Haskell, the fixed size Int types (Int8, Int16, Int32, Int64), the fixed size Word types (Word8, Word16, Word32, Word64), StablePtr, all types from Foreign.C.Types, as well as Ptr.