Foreign.Compat

The Bits class defines bitwise operations over integral types.

• Bits are numbered from 0 with bit 0 being the least significant bit.

Discard the return value of an IO action

Default implementation for bit.

Note that: bitDefault i = 1 shiftL i

Default implementation for popCount.

This implementation is intentionally naive. Instances are expected to provide an optimized implementation for their size.

Default implementation for testBit.

Note that: testBitDefault x i = (x .&. bit i) /= 0

Attempt to convert an Integral type a to an Integral type b using the size of the types as measured by Bits methods.

A simpler version of this function is:

toIntegral :: (Integral a, Integral b) => a -> Maybe b
toIntegral x
  | toInteger x == toInteger y = Just y
  | otherwise                  = Nothing
  where
    y = fromIntegral x

This version requires going through Integer, which can be inefficient. However, toIntegralSized is optimized to allow GHC to statically determine the relative type sizes (as measured by bitSizeMaybe and isSigned) and avoid going through Integer for many types. (The implementation uses fromIntegral, which is itself optimized with rules for base types but may go through Integer for some type pairs.)

Infix version of unsafeShiftL.

Infix version of unsafeShiftR.

Infix version of shiftL.

Infix version of shiftR.

Infix version of xor.

A more concise version of complement zeroBits.

>>> complement (zeroBits :: Word) == (oneBits :: Word)True

>>> complement (oneBits :: Word) == (zeroBits :: Word)True

Note

The constraint on oneBits is arguably too strong. However, as some types (such as Natural) have undefined complement, this is the only safe choice.

The FiniteBits class denotes types with a finite, fixed number of bits.

Monoid under bitwise AND.

>>> getAnd (And 0xab <> And 0x12) :: Word82

Monoid under bitwise 'equality'; defined as 1 if the corresponding bits match, and 0 otherwise.

>>> getIff (Iff 0xab <> Iff 0x12) :: Word870

Monoid under bitwise inclusive OR.

>>> getIor (Ior 0xab <> Ior 0x12) :: Word8187

Monoid under bitwise XOR.

>>> getXor (Xor 0xab <> Xor 0x12) :: Word8185

A fixed-precision integer type with at least the range [-2^29 .. 2^29-1]. The exact range for a given implementation can be determined by using Prelude.minBound and Prelude.maxBound from the Prelude.Bounded class.

A Word is an unsigned integral type, with the same size as Int.

32-bit unsigned integer type

64-bit unsigned integer type

16-bit unsigned integer type

8-bit unsigned integer type

A stable pointer is a reference to a Haskell expression that is guaranteed not to be affected by garbage collection, i.e., it will neither be deallocated nor will the value of the stable pointer itself change during garbage collection (ordinary references may be relocated during garbage collection). Consequently, stable pointers can be passed to foreign code, which can treat it as an opaque reference to a Haskell value.

The StablePtr 0 is reserved for representing NULL in foreign code.

A value of type StablePtr a is a stable pointer to a Haskell expression of type a.

Obtain the Haskell value referenced by a stable pointer, i.e., the same value that was passed to the corresponding call to newStablePtr. If the argument to deRefStablePtr has already been freed using freeStablePtr, the behaviour of deRefStablePtr is undefined.

Dissolve the association between the stable pointer and the Haskell value. Afterwards, if the stable pointer is passed to deRefStablePtr or freeStablePtr, the behaviour is undefined. However, the stable pointer may still be passed to castStablePtrToPtr, but the Ptr () value returned by castStablePtrToPtr, in this case, is undefined (in particular, it may be nullPtr). Nevertheless, the call to castStablePtrToPtr is guaranteed not to diverge.

Create a stable pointer referring to the given Haskell value.

64-bit signed integer type

32-bit signed integer type

16-bit signed integer type

8-bit signed integer type

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.

A value of type Ptr a represents a pointer to an object, or an array of objects, which may be marshalled to or from Haskell values of type a.

The type a will often be an instance of class Storable which provides the marshalling operations. However this is not essential, and you can provide your own operations to access the pointer. For example you might write small foreign functions to get or set the fields of a C struct.

The castPtr function casts a pointer from one type to another.

The inverse of castStablePtrToPtr, i.e., we have the identity

sp == castPtrToStablePtr (castStablePtrToPtr sp)

for any stable pointer sp on which freeStablePtr has not been executed yet. Moreover, castPtrToStablePtr may only be applied to pointers that have been produced by castStablePtrToPtr.

Coerce a stable pointer to an address. No guarantees are made about the resulting value, except that the original stable pointer can be recovered by castPtrToStablePtr. In particular, the address might not refer to an accessible memory location and any attempt to pass it to the member functions of the class Storable leads to undefined behaviour.

Allocate a block of memory and marshal a value into it (the combination of malloc and poke). The size of the area allocated is determined by the sizeOf method from the instance of Storable for the appropriate type.

The memory may be deallocated using free or finalizerFree when no longer required.

A value of type FunPtr a is a pointer to a function callable from foreign code. The type a will normally be a foreign type, a function type with zero or more arguments where

• the argument types are marshallable foreign types, i.e. Char, Int, Double, Float, Bool, Int8, Int16, Int32, Int64, Word8, Word16, Word32, Word64, Ptr a, FunPtr a, StablePtr a or a renaming of any of these using newtype.

• the return type is either a marshallable foreign type or has the form IO t where t is a marshallable foreign type or ().

A value of type FunPtr a may be a pointer to a foreign function, either returned by another foreign function or imported with a a static address import like

foreign import ccall "stdlib.h &free"
  p_free :: FunPtr (Ptr a -> IO ())

or a pointer to a Haskell function created using a wrapper stub declared to produce a FunPtr of the correct type. For example:

type Compare = Int -> Int -> Bool
foreign import ccall "wrapper"
  mkCompare :: Compare -> IO (FunPtr Compare)

Calls to wrapper stubs like mkCompare allocate storage, which should be released with freeHaskellFunPtr when no longer required.

To convert FunPtr values to corresponding Haskell functions, one can define a dynamic stub for the specific foreign type, e.g.

type IntFunction = CInt -> IO ()
foreign import ccall "dynamic"
  mkFun :: FunPtr IntFunction -> IntFunction

Reverse the order of the bits in a Word16.

Reverse the order of the bits in a Word32.

Reverse the order of the bits in a Word64.

Reverse the order of the bits in a Word8.

Reverse order of bytes in Word16.

Reverse order of bytes in Word32.

Reverse order of bytes in Word64.

This function is similar to mallocArray, but yields a memory area that has a finalizer attached that releases the memory area. As with mallocForeignPtr, it is not guaranteed that the block of memory was allocated by malloc.

This function is similar to mallocArray0, but yields a memory area that has a finalizer attached that releases the memory area. As with mallocForeignPtr, it is not guaranteed that the block of memory was allocated by malloc.

Turns a plain memory reference into a foreign pointer, and associates a finalizer with the reference. The finalizer will be executed after the last reference to the foreign object is dropped. There is no guarantee of promptness, however the finalizer will be executed before the program exits.

This variant of newForeignPtr adds a finalizer that expects an environment in addition to the finalized pointer. The environment that will be passed to the finalizer is fixed by the second argument to newForeignPtrEnv.

alloca f executes the computation f, passing as argument a pointer to a temporarily allocated block of memory sufficient to hold values of type a.

The memory is freed when f terminates (either normally or via an exception), so the pointer passed to f must not be used after this.

allocaBytes n f executes the computation f, passing as argument a pointer to a temporarily allocated block of memory of n bytes. The block of memory is sufficiently aligned for any of the basic foreign types that fits into a memory block of the allocated size.

The memory is freed when f terminates (either normally or via an exception), so the pointer passed to f must not be used after this.

allocaBytesAligned size align f executes the computation f, passing as argument a pointer to a temporarily allocated block of memory of size bytes and aligned to align bytes. The value of align must be a power of two.

The memory is freed when f terminates (either normally or via an exception), so the pointer passed to f must not be used after this.

Like malloc but memory is filled with bytes of value zero.

Like mallocBytes, but memory is filled with bytes of value zero.

A pointer to a foreign function equivalent to free, which may be used as a finalizer (cf ForeignPtr) for storage allocated with malloc, mallocBytes, realloc or reallocBytes.

Free a block of memory that was allocated with malloc, mallocBytes, realloc, reallocBytes, new or any of the newX functions in Foreign.Marshal.Array or Foreign.C.String.

Allocate a block of memory that is sufficient to hold values of type a. The size of the area allocated is determined by the sizeOf method from the instance of Storable for the appropriate type.

The memory may be deallocated using free or finalizerFree when no longer required.

Allocate a block of memory of the given number of bytes. The block of memory is sufficiently aligned for any of the basic foreign types that fits into a memory block of the allocated size.

The memory may be deallocated using free or finalizerFree when no longer required.

Resize a memory area that was allocated with malloc or mallocBytes to the size needed to store values of type b. The returned pointer may refer to an entirely different memory area, but will be suitably aligned to hold values of type b. The contents of the referenced memory area will be the same as of the original pointer up to the minimum of the original size and the size of values of type b.

If the argument to realloc is nullPtr, realloc behaves like malloc.

Resize a memory area that was allocated with malloc or mallocBytes to the given size. The returned pointer may refer to an entirely different memory area, but will be sufficiently aligned for any of the basic foreign types that fits into a memory block of the given size. The contents of the referenced memory area will be the same as of the original pointer up to the minimum of the original size and the given size.

If the pointer argument to reallocBytes is nullPtr, reallocBytes behaves like malloc. If the requested size is 0, reallocBytes behaves like free.

Advance a pointer into an array by the given number of elements

Temporarily allocate space for the given number of elements (like alloca, but for multiple elements).

Like allocaArray, but add an extra position to hold a special termination element.

Like mallocArray, but allocated memory is filled with bytes of value zero.

Like callocArray0, but allocated memory is filled with bytes of value zero.

Copy the given number of elements from the second array (source) into the first array (destination); the copied areas may not overlap

Return the number of elements in an array, excluding the terminator

Allocate storage for the given number of elements of a storable type (like malloc, but for multiple elements).

Like mallocArray, but add an extra position to hold a special termination element.

Copy the given number of elements from the second array (source) into the first array (destination); the copied areas may overlap

Write a list of storable elements into a newly allocated, consecutive sequence of storable values (like new, but for multiple elements).

Write a list of storable elements into a newly allocated, consecutive sequence of storable values, where the end is fixed by the given end marker

Convert an array of given length into a Haskell list. The implementation is tail-recursive and so uses constant stack space.

Convert an array terminated by the given end marker into a Haskell list

Write the list elements consecutive into memory

Write the list elements consecutive into memory and terminate them with the given marker element

Adjust the size of an array

Adjust the size of an array including an extra position for the end marker.

Temporarily store a list of storable values in memory (like with, but for multiple elements).

Like withArray, but a terminator indicates where the array ends

Like withArray, but the action gets the number of values as an additional parameter

Like withArrayLen, but a terminator indicates where the array ends

Execute an IO action, throwing a userError if the predicate yields True when applied to the result returned by the IO action. If no exception is raised, return the result of the computation.

Guards against negative result values

Like throwIfNeg, but discarding the result

Guards against null pointers

Like throwIf, but discarding the result

Deallocate a memory pool and everything which has been allocated in the pool itself.

Allocate a fresh memory pool.

Allocate space for storable type in the given pool. The size of the area allocated is determined by the sizeOf method from the instance of Storable for the appropriate type.

Allocate storage for the given number of elements of a storable type in the pool.

Allocate storage for the given number of elements of a storable type in the pool, but leave room for an extra element to signal the end of the array.

Allocate the given number of bytes of storage in the pool.

Allocate storage for a value in the given pool and marshal the value into this storage.

Allocate consecutive storage for a list of values in the given pool and marshal these values into it.

Allocate consecutive storage for a list of values in the given pool and marshal these values into it, terminating the end with the given marker.

Adjust the storage area for an element in the pool to the given size of the required type.

Adjust the size of an array in the given pool.

Adjust the size of an array with an end marker in the given pool.

Adjust the storage area for an element in the pool to the given size. Note that the previously allocated space is still retained in the same Pool and will only be freed when the entire Pool is freed.

Execute an action with a fresh memory pool, which gets automatically deallocated (including its contents) after the action has finished.

Copies the given number of bytes from the second area (source) into the first (destination); the copied areas may not overlap

Fill a given number of bytes in memory area with a byte value.

Convert a Haskell Bool to its numeric representation

Allocate storage and marshal a storable value wrapped into a Maybe

• the nullPtr is used to represent Nothing

Convert a peek combinator into a one returning Nothing if applied to a nullPtr

Converts a withXXX combinator into one marshalling a value wrapped into a Maybe, using nullPtr to represent Nothing.

Copies the given number of bytes from the second area (source) into the first (destination); the copied areas may overlap

Convert a Boolean in numeric representation to a Haskell value

with val f executes the computation f, passing as argument a pointer to a temporarily allocated block of memory into which val has been marshalled (the combination of alloca and poke).

The memory is freed when f terminates (either normally or via an exception), so the pointer passed to f must not be used after this.

Replicates a withXXX combinator over a list of objects, yielding a list of marshalled objects

Release the storage associated with the given FunPtr, which must have been obtained from a wrapper stub. This should be called whenever the return value from a foreign import wrapper function is no longer required; otherwise, the storage it uses will leak.

casts an IntPtr to a Ptr

casts a Ptr to an IntPtr

casts a Ptr to a WordPtr

casts a WordPtr to a Ptr

This function adds a finalizer to the given foreign object. The finalizer will run before all other finalizers for the same object which have already been registered.

Like addForeignPtrFinalizer but the finalizer is passed an additional environment parameter.

This function casts a ForeignPtr parameterised by one type into another type.

Causes the finalizers associated with a foreign pointer to be run immediately. The foreign pointer must not be used again after this function is called. If the foreign pointer does not support finalizers, this is a no-op.

Allocate some memory and return a ForeignPtr to it. The memory will be released automatically when the ForeignPtr is discarded.

mallocForeignPtr is equivalent to

   do { p <- malloc; newForeignPtr finalizerFree p }

although it may be implemented differently internally: you may not assume that the memory returned by mallocForeignPtr has been allocated with malloc.

GHC notes: mallocForeignPtr has a heavily optimised implementation in GHC. It uses pinned memory in the garbage collected heap, so the ForeignPtr does not require a finalizer to free the memory. Use of mallocForeignPtr and associated functions is strongly recommended in preference to newForeignPtr with a finalizer.

This function is similar to mallocForeignPtr, except that the size of the memory required is given explicitly as a number of bytes.

Turns a plain memory reference into a foreign pointer that may be associated with finalizers by using addForeignPtrFinalizer.

Advances the given address by the given offset in bytes.

The new ForeignPtr shares the finalizer of the original, equivalent from a finalization standpoint to just creating another reference to the original. That is, the finalizer will not be called before the new ForeignPtr is unreachable, nor will it be called an additional time due to this call, and the finalizer will be called with the same address that it would have had this call not happened, *not* the new address.

This function ensures that the foreign object in question is alive at the given place in the sequence of IO actions. However, this comes with a significant caveat: the contract above does not hold if GHC can demonstrate that the code preceding touchForeignPtr diverges (e.g. by looping infinitely or throwing an exception). For this reason, you are strongly advised to use instead withForeignPtr where possible.

Also, note that this function should not be used to express dependencies between finalizers on ForeignPtrs. For example, if the finalizer for a ForeignPtr F1 calls touchForeignPtr on a second ForeignPtr F2, then the only guarantee is that the finalizer for F2 is never started before the finalizer for F1. They might be started together if for example both F1 and F2 are otherwise unreachable, and in that case the scheduler might end up running the finalizer for F2 first.

In general, it is not recommended to use finalizers on separate objects with ordering constraints between them. To express the ordering robustly requires explicit synchronisation using MVars between the finalizers, but even then the runtime sometimes runs multiple finalizers sequentially in a single thread (for performance reasons), so synchronisation between finalizers could result in artificial deadlock. Another alternative is to use explicit reference counting.

This is a way to look at the pointer living inside a foreign object. This function takes a function which is applied to that pointer. The resulting IO action is then executed. The foreign object is kept alive at least during the whole action, even if it is not used directly inside. Note that it is not safe to return the pointer from the action and use it after the action completes. All uses of the pointer should be inside the withForeignPtr bracket. The reason for this unsafeness is the same as for unsafeForeignPtrToPtr below: the finalizer may run earlier than expected, because the compiler can only track usage of the ForeignPtr object, not a Ptr object made from it.

This function is normally used for marshalling data to or from the object pointed to by the ForeignPtr, using the operations from the Storable class.

Given an arbitrary address and an alignment constraint, alignPtr yields the next higher address that fulfills the alignment constraint. An alignment constraint x is fulfilled by any address divisible by x. This operation is idempotent.

Casts a FunPtr to a FunPtr of a different type.

Casts a FunPtr to a Ptr.

Note: this is valid only on architectures where data and function pointers range over the same set of addresses, and should only be used for bindings to external libraries whose interface already relies on this assumption.

Casts a Ptr to a FunPtr.

Note: this is valid only on architectures where data and function pointers range over the same set of addresses, and should only be used for bindings to external libraries whose interface already relies on this assumption.

Computes the offset required to get from the second to the first argument. We have

p2 == p1 `plusPtr` (p2 `minusPtr` p1)

The constant nullFunPtr contains a distinguished value of FunPtr that is not associated with a valid memory location.

The constant nullPtr contains a distinguished value of Ptr that is not associated with a valid memory location.

Advances the given address by the given offset in bytes.

A memory pool.

A signed integral type that can be losslessly converted to and from Ptr. This type is also compatible with the C99 type intptr_t, and can be marshalled to and from that type safely.

An unsigned integral type that can be losslessly converted to and from Ptr. This type is also compatible with the C99 type uintptr_t, and can be marshalled to and from that type safely.

A finalizer is represented as a pointer to a foreign function that, at finalisation time, gets as an argument a plain pointer variant of the foreign pointer that the finalizer is associated with.

Note that the foreign function must either use the ccall or the capi calling convention.

The type ForeignPtr represents references to objects that are maintained in a foreign language, i.e., that are not part of the data structures usually managed by the Haskell storage manager. The essential difference between ForeignPtrs and vanilla memory references of type Ptr a is that the former may be associated with finalizers. A finalizer is a routine that is invoked when the Haskell storage manager detects that - within the Haskell heap and stack - there are no more references left that are pointing to the ForeignPtr. Typically, the finalizer will, then, invoke routines in the foreign language that free the resources bound by the foreign object.

The ForeignPtr is parameterised in the same way as Ptr. The type argument of ForeignPtr should normally be an instance of class Storable.