ghc-prim-0.2.0.0: GHC primitives

Portabilitynon-portable (GHC extensions)
Stabilityinternal
Maintainercvs-ghc@haskell.org

GHC.Prim

Contents

Description

GHC's primitive types and operations. Use GHC.Exts from the base package instead of importing this module directly.

Synopsis

The word size story.

Haskell98 specifies that signed integers (type Int) must contain at least 30 bits. GHC always implements Int using the primitive type Int#, whose size equals the MachDeps.h constant WORD_SIZE_IN_BITS. This is normally set based on the config.h parameter SIZEOF_HSWORD, i.e., 32 bits on 32-bit machines, 64 bits on 64-bit machines. However, it can also be explicitly set to a smaller number, e.g., 31 bits, to allow the possibility of using tag bits. Currently GHC itself has only 32-bit and 64-bit variants, but 30 or 31-bit code can be exported as an external core file for use in other back ends.

GHC also implements a primitive unsigned integer type Word# which always has the same number of bits as Int#.

In addition, GHC supports families of explicit-sized integers and words at 8, 16, 32, and 64 bits, with the usual arithmetic operations, comparisons, and a range of conversions. The 8-bit and 16-bit sizes are always represented as Int# and Word#, and the operations implemented in terms of the the primops on these types, with suitable range restrictions on the results (using the narrow$n$Int# and narrow$n$Word# families of primops. The 32-bit sizes are represented using Int# and Word# when WORD_SIZE_IN_BITS $geq$ 32; otherwise, these are represented using distinct primitive types Int32# and Word32#. These (when needed) have a complete set of corresponding operations; however, nearly all of these are implemented as external C functions rather than as primops. Exactly the same story applies to the 64-bit sizes. All of these details are hidden under the PrelInt and PrelWord modules, which use #if-defs to invoke the appropriate types and operators.

Word size also matters for the families of primops for indexing/reading/writing fixed-size quantities at offsets from an array base, address, or foreign pointer. Here, a slightly different approach is taken. The names of these primops are fixed, but their types vary according to the value of WORD_SIZE_IN_BITS. For example, if word size is at least 32 bits then an operator like indexInt32Array# has type ByteArray# -> Int# -> Int#; otherwise it has type ByteArray# -> Int# -> Int32#. This approach confines the necessary #if-defs to this file; no conditional compilation is needed in the files that expose these primops.

Finally, there are strongly deprecated primops for coercing between Addr#, the primitive type of machine addresses, and Int#. These are pretty bogus anyway, but will work on existing 32-bit and 64-bit GHC targets; they are completely bogus when tag bits are used in Int#, so are not available in this case.

Char#

Operations on 31-bit characters.

Int#

Operations on native-size integers (30+ bits).

(*#) :: Int# -> Int# -> Int#Source

Low word of signed integer multiply.

mulIntMayOflo# :: Int# -> Int# -> Int#Source

Return non-zero if there is any possibility that the upper word of a signed integer multiply might contain useful information. Return zero only if you are completely sure that no overflow can occur. On a 32-bit platform, the recommmended implementation is to do a 32 x 32 -> 64 signed multiply, and subtract result[63:32] from (result[31] >>signed 31). If this is zero, meaning that the upper word is merely a sign extension of the lower one, no overflow can occur.

On a 64-bit platform it is not always possible to acquire the top 64 bits of the result. Therefore, a recommended implementation is to take the absolute value of both operands, and return 0 iff bits[63:31] of them are zero, since that means that their magnitudes fit within 31 bits, so the magnitude of the product must fit into 62 bits.

If in doubt, return non-zero, but do make an effort to create the correct answer for small args, since otherwise the performance of (*) :: Integer -> Integer -> Integer will be poor.

quotInt# :: Int# -> Int# -> Int#Source

Rounds towards zero.

remInt# :: Int# -> Int# -> Int#Source

Satisfies (quotInt# x y) *# y +# (remInt# x y) == x.

addIntC# :: Int# -> Int# -> (#Int#, Int##)Source

Add with carry. First member of result is (wrapped) sum; second member is 0 iff no overflow occured.

subIntC# :: Int# -> Int# -> (#Int#, Int##)Source

Subtract with carry. First member of result is (wrapped) difference; second member is 0 iff no overflow occured.

uncheckedIShiftL# :: Int# -> Int# -> Int#Source

Shift left. Result undefined if shift amount is not in the range 0 to word size - 1 inclusive.

uncheckedIShiftRA# :: Int# -> Int# -> Int#Source

Shift right arithmetic. Result undefined if shift amount is not in the range 0 to word size - 1 inclusive.

uncheckedIShiftRL# :: Int# -> Int# -> Int#Source

Shift right logical. Result undefined if shift amount is not in the range 0 to word size - 1 inclusive.

Word#

Operations on native-sized unsigned words (30+ bits).

uncheckedShiftL# :: Word# -> Int# -> Word#Source

Shift left logical. Result undefined if shift amount is not in the range 0 to word size - 1 inclusive.

uncheckedShiftRL# :: Word# -> Int# -> Word#Source

Shift right logical. Result undefined if shift amount is not in the range 0 to word size - 1 inclusive.

Narrowings

Explicit narrowing of native-sized ints or words.

Double#

Operations on double-precision (64 bit) floating-point numbers.

double2Int# :: Double# -> Int#Source

Truncates a Double. Results are undefined if the truncation if truncation yields a value outside the range of Int#.

(**##) :: Double# -> Double# -> Double#Source

Exponentiation.

decodeDouble_2Int# :: Double# -> (#Int#, Word#, Word#, Int##)Source

Convert to integer. First component of the result is -1 or 1, indicating the sign of the mantissa. The next two are the high and low 32 bits of the mantissa respectively, and the last is the exponent.

Float#

Operations on single-precision (32-bit) floating-point numbers.

float2Int# :: Float# -> Int#Source

Truncates a Float. Results are undefined if the truncation if truncation yields a value outside the range of Int#.

decodeFloat_Int# :: Float# -> (#Int#, Int##)Source

Convert to integers. First Int# in result is the mantissa; second is the exponent.

Arrays

Operations on Array#.

data Array# a Source

newArray# :: Int# -> a -> State# s -> (#State# s, MutableArray# s a#)Source

Create a new mutable array with the specified number of elements, in the specified state thread, with each element containing the specified initial value.

readArray# :: MutableArray# s a -> Int# -> State# s -> (#State# s, a#)Source

Read from specified index of mutable array. Result is not yet evaluated.

writeArray# :: MutableArray# s a -> Int# -> a -> State# s -> State# sSource

Write to specified index of mutable array.

indexArray# :: Array# a -> Int# -> (#a#)Source

Read from specified index of immutable array. Result is packaged into an unboxed singleton; the result itself is not yet evaluated.

unsafeFreezeArray# :: MutableArray# s a -> State# s -> (#State# s, Array# a#)Source

Make a mutable array immutable, without copying.

unsafeThawArray# :: Array# a -> State# s -> (#State# s, MutableArray# s a#)Source

Make an immutable array mutable, without copying.

Byte Arrays

Operations on ByteArray#. A ByteArray# is a just a region of raw memory in the garbage-collected heap, which is not scanned for pointers. It carries its own size (in bytes). There are three sets of operations for accessing byte array contents: index for reading from immutable byte arrays, and read/write for mutable byte arrays. Each set contains operations for a range of useful primitive data types. Each operation takes an offset measured in terms of the size fo the primitive type being read or written.

newByteArray# :: Int# -> State# s -> (#State# s, MutableByteArray# s#)Source

Create a new mutable byte array of specified size (in bytes), in the specified state thread.

newPinnedByteArray# :: Int# -> State# s -> (#State# s, MutableByteArray# s#)Source

Create a mutable byte array that the GC guarantees not to move.

newAlignedPinnedByteArray# :: Int# -> Int# -> State# s -> (#State# s, MutableByteArray# s#)Source

Create a mutable byte array, aligned by the specified amount, that the GC guarantees not to move.

byteArrayContents# :: ByteArray# -> Addr#Source

Intended for use with pinned arrays; otherwise very unsafe!

unsafeFreezeByteArray# :: MutableByteArray# s -> State# s -> (#State# s, ByteArray##)Source

Make a mutable byte array immutable, without copying.

sizeofByteArray# :: ByteArray# -> Int#Source

Return the size of the array in bytes.

sizeofMutableByteArray# :: MutableByteArray# s -> Int#Source

Return the size of the array in bytes.

indexCharArray# :: ByteArray# -> Int# -> Char#Source

Read 8-bit character; offset in bytes.

indexWideCharArray# :: ByteArray# -> Int# -> Char#Source

Read 31-bit character; offset in 4-byte words.

readCharArray# :: MutableByteArray# s -> Int# -> State# s -> (#State# s, Char##)Source

Read 8-bit character; offset in bytes.

readWideCharArray# :: MutableByteArray# s -> Int# -> State# s -> (#State# s, Char##)Source

Read 31-bit character; offset in 4-byte words.

writeCharArray# :: MutableByteArray# s -> Int# -> Char# -> State# s -> State# sSource

Write 8-bit character; offset in bytes.

writeWideCharArray# :: MutableByteArray# s -> Int# -> Char# -> State# s -> State# sSource

Write 31-bit character; offset in 4-byte words.

Addr#

 

data Addr# Source

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

nullAddr# :: Addr#Source

The null address.

minusAddr# :: Addr# -> Addr# -> Int#Source

Result is meaningless if two Addr#s are so far apart that their difference doesn't fit in an Int#.

remAddr# :: Addr# -> Int# -> Int#Source

Return the remainder when the Addr# arg, treated like an Int#, is divided by the Int# arg.

addr2Int# :: Addr# -> Int#Source

Coerce directly from address to int. Strongly deprecated.

int2Addr# :: Int# -> Addr#Source

Coerce directly from int to address. Strongly deprecated.

indexCharOffAddr# :: Addr# -> Int# -> Char#Source

Reads 8-bit character; offset in bytes.

indexWideCharOffAddr# :: Addr# -> Int# -> Char#Source

Reads 31-bit character; offset in 4-byte words.

readCharOffAddr# :: Addr# -> Int# -> State# s -> (#State# s, Char##)Source

Reads 8-bit character; offset in bytes.

readWideCharOffAddr# :: Addr# -> Int# -> State# s -> (#State# s, Char##)Source

Reads 31-bit character; offset in 4-byte words.

Mutable variables

Operations on MutVar#s.

data MutVar# s a Source

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

newMutVar# :: a -> State# s -> (#State# s, MutVar# s a#)Source

Create MutVar# with specified initial value in specified state thread.

readMutVar# :: MutVar# s a -> State# s -> (#State# s, a#)Source

Read contents of MutVar#. Result is not yet evaluated.

writeMutVar# :: MutVar# s a -> a -> State# s -> State# sSource

Write contents of MutVar#.

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

Exceptions

 

raise# :: a -> bSource

STM-accessible Mutable Variables

 

data TVar# s a Source

newTVar# :: a -> State# s -> (#State# s, TVar# s a#)Source

Create a new TVar# holding a specified initial value.

readTVar# :: TVar# s a -> State# s -> (#State# s, a#)Source

Read contents of TVar#. Result is not yet evaluated.

readTVarIO# :: TVar# s a -> State# s -> (#State# s, a#)Source

Read contents of TVar# outside an STM transaction

writeTVar# :: TVar# s a -> a -> State# s -> State# sSource

Write contents of TVar#.

sameTVar# :: TVar# s a -> TVar# s a -> BoolSource

Synchronized Mutable Variables

Operations on MVar#s.

data MVar# s a Source

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

newMVar# :: State# s -> (#State# s, MVar# s a#)Source

Create new MVar#; initially empty.

takeMVar# :: MVar# s a -> State# s -> (#State# s, a#)Source

If MVar# is empty, block until it becomes full. Then remove and return its contents, and set it empty.

tryTakeMVar# :: MVar# s a -> State# s -> (#State# s, Int#, a#)Source

If MVar# is empty, immediately return with integer 0 and value undefined. Otherwise, return with integer 1 and contents of MVar#, and set MVar# empty.

putMVar# :: MVar# s a -> a -> State# s -> State# sSource

If MVar# is full, block until it becomes empty. Then store value arg as its new contents.

tryPutMVar# :: MVar# s a -> a -> State# s -> (#State# s, Int##)Source

If MVar# is full, immediately return with integer 0. Otherwise, store value arg as MVar#'s new contents, and return with integer 1.

sameMVar# :: MVar# s a -> MVar# s a -> BoolSource

isEmptyMVar# :: MVar# s a -> State# s -> (#State# s, Int##)Source

Return 1 if MVar# is empty; 0 otherwise.

Delay/wait operations

 

delay# :: Int# -> State# s -> State# sSource

Sleep specified number of microseconds.

waitRead# :: Int# -> State# s -> State# sSource

Block until input is available on specified file descriptor.

waitWrite# :: Int# -> State# s -> State# sSource

Block until output is possible on specified file descriptor.

Concurrency primitives

 

data State# s Source

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.

data RealWorld Source

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

data ThreadId# Source

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

Weak pointers

 

data Weak# b Source

mkWeak# :: o -> b -> c -> State# RealWorld -> (#State# RealWorld, Weak# b#)Source

Stable pointers and names

 

Unsafe pointer equality

 

Parallelism

 

getSpark# :: State# s -> (#State# s, Int#, a#)Source

numSparks# :: State# s -> (#State# s, Int##)Source

Returns the number of sparks in the local spark pool.

parGlobal# :: a -> Int# -> Int# -> Int# -> Int# -> b -> Int#Source

parLocal# :: a -> Int# -> Int# -> Int# -> Int# -> b -> Int#Source

parAt# :: b -> a -> Int# -> Int# -> Int# -> Int# -> c -> Int#Source

parAtAbs# :: a -> Int# -> Int# -> Int# -> Int# -> Int# -> b -> Int#Source

parAtRel# :: a -> Int# -> Int# -> Int# -> Int# -> Int# -> b -> Int#Source

parAtForNow# :: b -> a -> Int# -> Int# -> Int# -> Int# -> c -> Int#Source

Tag to enum stuff

Convert back and forth between values of enumerated types and small integers.

Bytecode operations

Support for the bytecode interpreter and linker.

data BCO# Source

Primitive bytecode type.

addrToHValue# :: Addr# -> (#a#)Source

Convert an Addr# to a followable type.

mkApUpd0# :: BCO# -> (#a#)Source

getApStackVal# :: a -> Int# -> (#Int#, b#)Source

Misc

These aren't nearly as wired in as Etc...

traceCcs# :: a -> b -> bSource

Etc

Miscellaneous built-ins

seq :: a -> b -> bSource

Evaluates its first argument to head normal form, and then returns its second argument as the result.

inline :: a -> aSource

The call (inline f) arranges that f is inlined, regardless of its size. More precisely, the call (inline f) rewrites to the right-hand side of f's definition. This allows the programmer to control inlining from a particular call site rather than the definition site of the function (c.f. INLINE pragmas in User's Guide, Section 7.10.3, "INLINE and NOINLINE pragmas").

This inlining occurs regardless of the argument to the call or the size of f's definition; it is unconditional. The main caveat is that f's definition must be visible to the compiler. That is, f must be let-bound in the current scope. If no inlining takes place, the inline function expands to the identity function in Phase zero; so its use imposes no overhead.

It is good practice to mark the function with an INLINABLE pragma at its definition, (a) so that GHC guarantees to expose its unfolding regardless of size, and (b) so that you have control over exactly what is inlined.

lazy :: a -> aSource

The lazy function restrains strictness analysis a little. The call (lazy e) means the same as e, but lazy has a magical property so far as strictness analysis is concerned: it is lazy in its first argument, even though its semantics is strict. After strictness analysis has run, calls to lazy are inlined to be the identity function.

This behaviour is occasionally useful when controlling evaluation order. Notably, lazy is used in the library definition of Control.Parallel.par:

par :: a -> b -> b
par x y = case (par# x) of _ -> lazy y

If lazy were not lazy, par would look strict in y which would defeat the whole purpose of par.

Like seq, the argument of lazy can have an unboxed type.

data Any a Source

The type constructor Any is type to which you can unsafely coerce any lifted type, and back.

  • It is lifted, and hence represented by a pointer
  • It does not claim to be a data type, and that's important for the code generator, because the code gen may enter a data value but never enters a function value.

It's also used to instantiate un-constrained type variables after type checking. For example

length Any []

Annoyingly, we sometimes need Anys of other kinds, such as (* -> *) etc. This is a bit like tuples. We define a couple of useful ones here, and make others up on the fly. If any of these others end up being exported into interface files, we'll get a crash; at least until we add interface-file syntax to support them.

unsafeCoerce# :: a -> bSource

The function unsafeCoerce# allows you to side-step the typechecker entirely. That is, it allows you to coerce any type into any other type. If you use this function, you had better get it right, otherwise segmentation faults await. It is generally used when you want to write a program that you know is well-typed, but where Haskell's type system is not expressive enough to prove that it is well typed.

The following uses of unsafeCoerce# are supposed to work (i.e. not lead to spurious compile-time or run-time crashes):

  • Casting any lifted type to Any
  • Casting Any back to the real type
  • Casting an unboxed type to another unboxed type of the same size (but not coercions between floating-point and integral types)
  • Casting between two types that have the same runtime representation. One case is when the two types differ only in "phantom" type parameters, for example Ptr Int to Ptr Float, or [Int] to [Float] when the list is known to be empty. Also, a newtype of a type T has the same representation at runtime as T.

Other uses of unsafeCoerce# are undefined. In particular, you should not use unsafeCoerce# to cast a T to an algebraic data type D, unless T is also an algebraic data type. For example, do not cast Int->Int to Bool, even if you later cast that Bool back to Int->Int before applying it. The reasons have to do with GHC's internal representation details (for the congnoscenti, data values can be entered but function closures cannot). If you want a safe type to cast things to, use Any, which is not an algebraic data type.

traceEvent# :: Addr# -> State# s -> State# sSource

Emits an event via the RTS tracing framework. The contents of the event is the zero-terminated byte string passed as the first argument. The event will be emitted either to the .eventlog file, or to stderr, depending on the runtime RTS flags.