GHC.PrimOps

Copy a range of the ArrayArray# to the specified region in the MutableArrayArray#. Both arrays must fully contain the specified ranges, but this is not checked. The two arrays must not be the same array in different states, but this is not checked either.

Copy a range of the first MutableArrayArray# to the specified region in the second MutableArrayArray#. Both arrays must fully contain the specified ranges, but this is not checked. The regions are allowed to overlap, although this is only possible when the same array is provided as both the source and the destination.

Create a new mutable array of arrays with the specified number of elements, in the specified state thread, with each element recursively referring to the newly created array.

Compare the underlying pointers of two arrays of arrays.

Compare the underlying pointers of two mutable arrays of arrays.

Return the number of elements in the array.

Return the number of elements in the array.

Make a mutable array of arrays immutable, without copying.

A list producer that can be fused with foldr. This function is merely

   augment g xs = g (:) xs

but GHC's simplifier will transform an expression of the form foldr k z (augment g xs), which may arise after inlining, to g k (foldr k z xs), which avoids producing an intermediate list.

A list producer that can be fused with foldr. This function is merely

   build g = g (:) []

but GHC's simplifier will transform an expression of the form foldr k z (build g), which may arise after inlining, to g k z, which avoids producing an intermediate list.

Shift the argument left by the specified number of bits (which must be non-negative).

Shift the argument right (signed) by the specified number of bits (which must be non-negative). The RA means "right, arithmetic" (as opposed to RL for logical)

Shift the argument right (unsigned) by the specified number of bits (which must be non-negative). The RL means "right, logical" (as opposed to RA for arithmetic)

Shift the argument left by the specified number of bits (which must be non-negative).

Shift the argument right by the specified number of bits (which must be non-negative). The RL means "right, logical" (as opposed to RA for arithmetic) (although an arithmetic right shift wouldn't make sense for Word#)

The Down type allows you to reverse sort order conveniently. A value of type Down a contains a value of type a (represented as Down a).

If a has an Ord instance associated with it then comparing two values thus wrapped will give you the opposite of their normal sort order. This is particularly useful when sorting in generalised list comprehensions, as in: then sortWith by Down x.

>>> compare True FalseGT

>>> compare (Down True) (Down False)LT

If a has a Bounded instance then the wrapped instance also respects the reversed ordering by exchanging the values of minBound and maxBound.

>>> minBound :: Int-9223372036854775808

>>> minBound :: Down IntDown 9223372036854775807

All other instances of Down a behave as they do for a.

IsString is used in combination with the -XOverloadedStrings language extension to convert the literals to different string types.

For example, if you use the text package, you can say

{-# LANGUAGE OverloadedStrings  #-}

myText = "hello world" :: Text

Internally, the extension will convert this to the equivalent of

myText = fromString @Text ("hello world" :: String)

Note: You can use fromString in normal code as well, but the usual performance/memory efficiency problems with String apply.

The IsList class and its methods are intended to be used in conjunction with the OverloadedLists extension.

The Item type function returns the type of items of the structure l.

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

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.

Returns a [String] representing the current call stack. This can be useful for debugging.

The implementation uses the call-stack simulation maintained by the profiler, so it only works if the program was compiled with -prof and contains suitable SCC annotations (e.g. by using -fprof-auto). Otherwise, the list returned is likely to be empty or uninformative.

Highly, terribly dangerous coercion from one representation type to another. Misuse of this function can invite the garbage collector to trounce upon your data and then laugh in your face. You don't want this function. Really.

Deprecated, use SPEC directly instead.

Annotating a type with NoSpecConstr will make SpecConstr not specialise for arguments of that type, e. g., {-# ANN type SPEC ForceSpecConstr #-}.

An implementation of the old atomicModifyMutVar# primop in terms of the new atomicModifyMutVar2# primop, for backwards compatibility. The type of this function is a bit bogus. It's best to think of it as having type

atomicModifyMutVar#
  :: MutVar# s a
  -> (a -> (a, b))
  -> State# s
  -> (# State# s, b #)

but there may be code that uses this with other two-field record types.

The groupWith function uses the user supplied function which projects an element out of every list element in order to first sort the input list and then to form groups by equality on these projected elements

Resize a mutable array to new specified size. The returned SmallMutableArray# is either the original SmallMutableArray# resized in-place or, if not possible, a newly allocated SmallMutableArray# with the original content copied over.

To avoid undefined behaviour, the original SmallMutableArray# shall not be accessed anymore after a resizeSmallMutableArray# has been performed. Moreover, no reference to the old one should be kept in order to allow garbage collection of the original SmallMutableArray# in case a new SmallMutableArray# had to be allocated.

The sortWith function sorts a list of elements using the user supplied function to project something out of each element

In general if the user supplied function is expensive to compute then you should probably be using sortOn, as it only needs to compute it once for each element. sortWith, on the other hand must compute the mapping function for every comparison that it performs.

the ensures that all the elements of the list are identical and then returns that unique element

Retrieves the allocation counter for the current thread.

Compare two stable names for equality.

Compare the underlying pointers of two values for equality.

Returns 1 if the pointers are equal and 0 otherwise.

The two values must be of the same type, of kind Type. See also reallyUnsafePtrEquality#, which doesn't have such restrictions.

Compare the underlying pointers of two arrays.

Compare the pointers of two byte arrays.

Compare the underlying pointers of two IOPort#s.

Compare the underlying pointers of two MVar#s.

Compare the underlying pointers of two MutVar#s.

Compare the underlying pointers of two mutable arrays.

Compare the underlying pointers of two mutable byte arrays.

Compare the underlying pointers of two PromptTag#s.

Compare the underlying pointers of two small arrays.

Compare the underlying pointers of two small mutable arrays.

Compare the underlying pointers of two TVar#s.

Compare the underlying pointers of two unlifted values for equality.

This is less dangerous than reallyUnsafePtrEquality, since the arguments are guaranteed to be evaluated. This means there is no risk of accidentally comparing a thunk. It's however still more dangerous than e.g. sameArray#.

Alias for tagToEnum#. Returns True if its parameter is 1# and False if it is 0#.

dataToTag# evaluates its argument and returns the index (starting at zero) of the constructor used to produce that argument. Any algebraic data type with all of its constructors in scope may be used with dataToTag#.

>>> dataToTag# (Left ())0#>>> dataToTag# (Right undefined)1#

The constraint WithDict cls meth can be solved when evidence for the constraint cls can be provided in the form of a dictionary of type meth. This requires cls to be a class constraint whose single method has type meth.

For more (important) details on how this works, see Note [withDict] in GHC.Tc.Instance.Class in GHC.

SPEC is used by GHC in the SpecConstr pass in order to inform the compiler when to be particularly aggressive. In particular, it tells GHC to specialize regardless of size or the number of specializations. However, not all loops fall into this category.

Libraries can specify this by using SPEC data type to inform which loops should be aggressively specialized. For example, instead of

loop x where loop arg = ...

write

loop SPEC x where loop !_ arg = ...

There is no semantic difference between SPEC and SPEC2, we just need a type with two constructors lest it is optimised away before SpecConstr.

This type is reexported from GHC.Exts since GHC 9.0 and base-4.15. For compatibility with earlier releases import it from GHC.Types in ghc-prim package.

Static

Dynamic

An arbitrary machine address assumed to point outside the garbage-collected heap.

A boxed, unlifted datatype representing a region of raw memory in the garbage-collected heap, which is not scanned for pointers during garbage collection.

It is created by freezing a MutableByteArray# with unsafeFreezeByteArray#. Freezing is essentially a no-op, as MutableByteArray# and ByteArray# share the same heap structure under the hood.

The immutable and mutable variants are commonly used for scenarios requiring high-performance data structures, like Text, Primitive Vector, Unboxed Array, and ShortByteString.

Another application of fundamental importance is Integer, which is backed by ByteArray#.

The representation on the heap of a Byte Array is:

+------------+-----------------+-----------------------+
|            |                 |                       |
|   HEADER   | SIZE (in bytes) |       PAYLOAD         |
|            |                 |                       |
+------------+-----------------+-----------------------+

To obtain a pointer to actual payload (e.g., for FFI purposes) use byteArrayContents# or mutableByteArrayContents#.

Alternatively, enabling the UnliftedFFITypes extension allows to mention ByteArray# and MutableByteArray# in FFI type signatures directly.

Primitive bytecode type.

A mutable ByteAray#. It can be created in three ways:

• newByteArray#: Create an unpinned array.

• newPinnedByteArray#: This will create a pinned array,

• newAlignedPinnedByteArray#: This will create a pinned array, with a custom alignment.

Unpinned arrays can be moved around during garbage collection, so you must not store or pass pointers to these values if there is a chance for the garbage collector to kick in. That said, even unpinned arrays can be passed to unsafe FFI calls, because no garbage collection happens during these unsafe calls (see Guaranteed Call Safety in the GHC Manual). For safe FFI calls, byte arrays must be not only pinned, but also kept alive by means of the keepAlive# function for the duration of a call (that's because garbage collection cannot move a pinned array, but is free to scrap it altogether).

A shared mutable variable (not the same as a MutVar#!). (Note: in a non-concurrent implementation, (MVar# a) can be represented by (MutVar# (Maybe a)).)

A shared I/O port is almost the same as an MVar#. The main difference is that IOPort has no deadlock detection or deadlock breaking code that forcibly releases the lock.

A MutVar# behaves like a single-element mutable array.

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#.

State# is the primitive, unlifted type of states. It has one type parameter, thus State# RealWorld, or State# s, where s is a type variable. The only purpose of the type parameter is to keep different state threads separate. It is represented by nothing at all.

The type constructor Proxy# is used to bear witness to some type variable. It's used when you want to pass around proxy values for doing things like modelling type applications. A Proxy# is not only unboxed, it also has a polymorphic kind, and has no runtime representation, being totally free.

(In a non-concurrent implementation, this can be a singleton type, whose (unique) value is returned by myThreadId#. The other operations can be omitted.)

Haskell representation of a StgStack* that was created (cloned) with a function in GHC.Stack.CloneStack. Please check the documentation in that module for more detailed explanations.

See GHC.Prim#continuations.

The builtin function type, written in infix form as a % m -> b. Values of this type are functions taking inputs of type a and producing outputs of type b. The multiplicity of the input is m.

Note that FUN m a b permits representation polymorphism in both a and b, so that types like Int# -> Int# can still be well-kinded.