--- /dev/null
+<!-- UNBOXED TYPES AND PRIMITIVE OPERATIONS -->
+
+<sect1 id="primitives">
+ <title>Unboxed types and primitive operations</title>
+ <indexterm><primary>PrelGHC module</primary></indexterm>
+
+ <para>This module defines all the types which are primitive in
+ Glasgow Haskell, and the operations provided for them.</para>
+
+ <para>Note: while you really can use this stuff to write fast code,
+ we generally find it a lot less painful, and more satisfying in the
+ long run, to use higher-level language features and libraries. With
+ any luck, the code you write will be optimised to the efficient
+ unboxed version in any case. And if it isn't, we'd like to know
+ about it.</para>
+
+<sect2 id="glasgow-unboxed">
+<title>Unboxed types
+</title>
+
+<para>
+<indexterm><primary>Unboxed types (Glasgow extension)</primary></indexterm>
+</para>
+
+<para>Most types in GHC are <firstterm>boxed</firstterm>, which means
+that values of that type are represented by a pointer to a heap
+object. The representation of a Haskell <literal>Int</literal>, for
+example, is a two-word heap object. An <firstterm>unboxed</firstterm>
+type, however, is represented by the value itself, no pointers or heap
+allocation are involved.
+</para>
+
+<para>
+Unboxed types correspond to the “raw machine” types you
+would use in C: <literal>Int#</literal> (long int),
+<literal>Double#</literal> (double), <literal>Addr#</literal>
+(void *), etc. The <emphasis>primitive operations</emphasis>
+(PrimOps) on these types are what you might expect; e.g.,
+<literal>(+#)</literal> is addition on
+<literal>Int#</literal>s, and is the machine-addition that we all
+know and love—usually one instruction.
+</para>
+
+<para>
+Primitive (unboxed) types cannot be defined in Haskell, and are
+therefore built into the language and compiler. Primitive types are
+always unlifted; that is, a value of a primitive type cannot be
+bottom. We use the convention that primitive types, values, and
+operations have a <literal>#</literal> suffix.
+</para>
+
+<para>
+Primitive values are often represented by a simple bit-pattern, such
+as <literal>Int#</literal>, <literal>Float#</literal>,
+<literal>Double#</literal>. But this is not necessarily the case:
+a primitive value might be represented by a pointer to a
+heap-allocated object. Examples include
+<literal>Array#</literal>, the type of primitive arrays. A
+primitive array is heap-allocated because it is too big a value to fit
+in a register, and would be too expensive to copy around; in a sense,
+it is accidental that it is represented by a pointer. If a pointer
+represents a primitive value, then it really does point to that value:
+no unevaluated thunks, no indirections…nothing can be at the
+other end of the pointer than the primitive value.
+</para>
+
+<para>
+There are some restrictions on the use of primitive types, the main
+one being that you can't pass a primitive value to a polymorphic
+function or store one in a polymorphic data type. This rules out
+things like <literal>[Int#]</literal> (i.e. lists of primitive
+integers). The reason for this restriction is that polymorphic
+arguments and constructor fields are assumed to be pointers: if an
+unboxed integer is stored in one of these, the garbage collector would
+attempt to follow it, leading to unpredictable space leaks. Or a
+<function>seq</function> operation on the polymorphic component may
+attempt to dereference the pointer, with disastrous results. Even
+worse, the unboxed value might be larger than a pointer
+(<literal>Double#</literal> for instance).
+</para>
+
+<para>
+Nevertheless, A numerically-intensive program using unboxed types can
+go a <emphasis>lot</emphasis> faster than its “standard”
+counterpart—we saw a threefold speedup on one example.
+</para>
+
+</sect2>
+
+<sect2 id="unboxed-tuples">
+<title>Unboxed Tuples
+</title>
+
+<para>
+Unboxed tuples aren't really exported by <literal>PrelGHC</literal>,
+they're available by default with <option>-fglasgow-exts</option>. An
+unboxed tuple looks like this:
+</para>
+
+<para>
+
+<programlisting>
+(# e_1, ..., e_n #)
+</programlisting>
+
+</para>
+
+<para>
+where <literal>e_1..e_n</literal> are expressions of any
+type (primitive or non-primitive). The type of an unboxed tuple looks
+the same.
+</para>
+
+<para>
+Unboxed tuples are used for functions that need to return multiple
+values, but they avoid the heap allocation normally associated with
+using fully-fledged tuples. When an unboxed tuple is returned, the
+components are put directly into registers or on the stack; the
+unboxed tuple itself does not have a composite representation. Many
+of the primitive operations listed in this section return unboxed
+tuples.
+</para>
+
+<para>
+There are some pretty stringent restrictions on the use of unboxed tuples:
+</para>
+
+<para>
+
+<itemizedlist>
+<listitem>
+
+<para>
+ Unboxed tuple types are subject to the same restrictions as
+other unboxed types; i.e. they may not be stored in polymorphic data
+structures or passed to polymorphic functions.
+
+</para>
+</listitem>
+<listitem>
+
+<para>
+ Unboxed tuples may only be constructed as the direct result of
+a function, and may only be deconstructed with a <literal>case</literal> expression.
+eg. the following are valid:
+
+
+<programlisting>
+f x y = (# x+1, y-1 #)
+g x = case f x x of { (# a, b #) -> a + b }
+</programlisting>
+
+
+but the following are invalid:
+
+
+<programlisting>
+f x y = g (# x, y #)
+g (# x, y #) = x + y
+</programlisting>
+
+
+</para>
+</listitem>
+<listitem>
+
+<para>
+ No variable can have an unboxed tuple type. This is illegal:
+
+
+<programlisting>
+f :: (# Int, Int #) -> (# Int, Int #)
+f x = x
+</programlisting>
+
+
+because <literal>x</literal> has an unboxed tuple type.
+
+</para>
+</listitem>
+
+</itemizedlist>
+
+</para>
+
+<para>
+Note: we may relax some of these restrictions in the future.
+</para>
+
+<para>
+The <literal>IO</literal> and <literal>ST</literal> monads use unboxed
+tuples to avoid unnecessary allocation during sequences of operations.
+</para>
+
+</sect2>
+
+<sect2>
+<title>Character and numeric types</title>
+
+<indexterm><primary>character types, primitive</primary></indexterm>
+<indexterm><primary>numeric types, primitive</primary></indexterm>
+<indexterm><primary>integer types, primitive</primary></indexterm>
+<indexterm><primary>floating point types, primitive</primary></indexterm>
+<para>
+There are the following obvious primitive types:
+</para>
+
+<programlisting>
+type Char#
+type Int#
+type Word#
+type Addr#
+type Float#
+type Double#
+type Int64#
+type Word64#
+</programlisting>
+
+<indexterm><primary><literal>Char#</literal></primary></indexterm>
+<indexterm><primary><literal>Int#</literal></primary></indexterm>
+<indexterm><primary><literal>Word#</literal></primary></indexterm>
+<indexterm><primary><literal>Addr#</literal></primary></indexterm>
+<indexterm><primary><literal>Float#</literal></primary></indexterm>
+<indexterm><primary><literal>Double#</literal></primary></indexterm>
+<indexterm><primary><literal>Int64#</literal></primary></indexterm>
+<indexterm><primary><literal>Word64#</literal></primary></indexterm>
+
+<para>
+If you really want to know their exact equivalents in C, see
+<filename>ghc/includes/StgTypes.h</filename> in the GHC source tree.
+</para>
+
+<para>
+Literals for these types may be written as follows:
+</para>
+
+<para>
+
+<programlisting>
+1# an Int#
+1.2# a Float#
+1.34## a Double#
+'a'# a Char#; for weird characters, use e.g. '\o<octal>'#
+"a"# an Addr# (a `char *'); only characters '\0'..'\255' allowed
+</programlisting>
+
+<indexterm><primary>literals, primitive</primary></indexterm>
+<indexterm><primary>constants, primitive</primary></indexterm>
+<indexterm><primary>numbers, primitive</primary></indexterm>
+</para>
+
+</sect2>
+
+<sect2>
+<title>Comparison operations</title>
+
+<para>
+<indexterm><primary>comparisons, primitive</primary></indexterm>
+<indexterm><primary>operators, comparison</primary></indexterm>
+</para>
+
+<para>
+
+<programlisting>
+{>,>=,==,/=,<,<=}# :: Int# -> Int# -> Bool
+
+{gt,ge,eq,ne,lt,le}Char# :: Char# -> Char# -> Bool
+ -- ditto for Word# and Addr#
+</programlisting>
+
+<indexterm><primary><literal>>#</literal></primary></indexterm>
+<indexterm><primary><literal>>=#</literal></primary></indexterm>
+<indexterm><primary><literal>==#</literal></primary></indexterm>
+<indexterm><primary><literal>/=#</literal></primary></indexterm>
+<indexterm><primary><literal><#</literal></primary></indexterm>
+<indexterm><primary><literal><=#</literal></primary></indexterm>
+<indexterm><primary><literal>gt{Char,Word,Addr}#</literal></primary></indexterm>
+<indexterm><primary><literal>ge{Char,Word,Addr}#</literal></primary></indexterm>
+<indexterm><primary><literal>eq{Char,Word,Addr}#</literal></primary></indexterm>
+<indexterm><primary><literal>ne{Char,Word,Addr}#</literal></primary></indexterm>
+<indexterm><primary><literal>lt{Char,Word,Addr}#</literal></primary></indexterm>
+<indexterm><primary><literal>le{Char,Word,Addr}#</literal></primary></indexterm>
+</para>
+
+</sect2>
+
+<sect2>
+<title>Primitive-character operations</title>
+
+<para>
+<indexterm><primary>characters, primitive operations</primary></indexterm>
+<indexterm><primary>operators, primitive character</primary></indexterm>
+</para>
+
+<para>
+
+<programlisting>
+ord# :: Char# -> Int#
+chr# :: Int# -> Char#
+</programlisting>
+
+<indexterm><primary><literal>ord#</literal></primary></indexterm>
+<indexterm><primary><literal>chr#</literal></primary></indexterm>
+</para>
+
+</sect2>
+
+<sect2>
+<title>Primitive-<literal>Int</literal> operations</title>
+
+<para>
+<indexterm><primary>integers, primitive operations</primary></indexterm>
+<indexterm><primary>operators, primitive integer</primary></indexterm>
+</para>
+
+<para>
+
+<programlisting>
+{+,-,*,quotInt,remInt,gcdInt}# :: Int# -> Int# -> Int#
+negateInt# :: Int# -> Int#
+
+iShiftL#, iShiftRA#, iShiftRL# :: Int# -> Int# -> Int#
+ -- shift left, right arithmetic, right logical
+
+addIntC#, subIntC#, mulIntC# :: Int# -> Int# -> (# Int#, Int# #)
+ -- add, subtract, multiply with carry
+</programlisting>
+
+<indexterm><primary><literal>+#</literal></primary></indexterm>
+<indexterm><primary><literal>-#</literal></primary></indexterm>
+<indexterm><primary><literal>*#</literal></primary></indexterm>
+<indexterm><primary><literal>quotInt#</literal></primary></indexterm>
+<indexterm><primary><literal>remInt#</literal></primary></indexterm>
+<indexterm><primary><literal>gcdInt#</literal></primary></indexterm>
+<indexterm><primary><literal>iShiftL#</literal></primary></indexterm>
+<indexterm><primary><literal>iShiftRA#</literal></primary></indexterm>
+<indexterm><primary><literal>iShiftRL#</literal></primary></indexterm>
+<indexterm><primary><literal>addIntC#</literal></primary></indexterm>
+<indexterm><primary><literal>subIntC#</literal></primary></indexterm>
+<indexterm><primary><literal>mulIntC#</literal></primary></indexterm>
+<indexterm><primary>shift operations, integer</primary></indexterm>
+</para>
+
+<para>
+<emphasis>Note:</emphasis> No error/overflow checking!
+</para>
+
+</sect2>
+
+<sect2>
+<title>Primitive-<literal>Double</literal> and <literal>Float</literal> operations</title>
+
+<para>
+<indexterm><primary>floating point numbers, primitive</primary></indexterm>
+<indexterm><primary>operators, primitive floating point</primary></indexterm>
+</para>
+
+<para>
+
+<programlisting>
+{+,-,*,/}## :: Double# -> Double# -> Double#
+{<,<=,==,/=,>=,>}## :: Double# -> Double# -> Bool
+negateDouble# :: Double# -> Double#
+double2Int# :: Double# -> Int#
+int2Double# :: Int# -> Double#
+
+{plus,minux,times,divide}Float# :: Float# -> Float# -> Float#
+{gt,ge,eq,ne,lt,le}Float# :: Float# -> Float# -> Bool
+negateFloat# :: Float# -> Float#
+float2Int# :: Float# -> Int#
+int2Float# :: Int# -> Float#
+</programlisting>
+
+</para>
+
+<para>
+<indexterm><primary><literal>+##</literal></primary></indexterm>
+<indexterm><primary><literal>-##</literal></primary></indexterm>
+<indexterm><primary><literal>*##</literal></primary></indexterm>
+<indexterm><primary><literal>/##</literal></primary></indexterm>
+<indexterm><primary><literal><##</literal></primary></indexterm>
+<indexterm><primary><literal><=##</literal></primary></indexterm>
+<indexterm><primary><literal>==##</literal></primary></indexterm>
+<indexterm><primary><literal>=/##</literal></primary></indexterm>
+<indexterm><primary><literal>>=##</literal></primary></indexterm>
+<indexterm><primary><literal>>##</literal></primary></indexterm>
+<indexterm><primary><literal>negateDouble#</literal></primary></indexterm>
+<indexterm><primary><literal>double2Int#</literal></primary></indexterm>
+<indexterm><primary><literal>int2Double#</literal></primary></indexterm>
+</para>
+
+<para>
+<indexterm><primary><literal>plusFloat#</literal></primary></indexterm>
+<indexterm><primary><literal>minusFloat#</literal></primary></indexterm>
+<indexterm><primary><literal>timesFloat#</literal></primary></indexterm>
+<indexterm><primary><literal>divideFloat#</literal></primary></indexterm>
+<indexterm><primary><literal>gtFloat#</literal></primary></indexterm>
+<indexterm><primary><literal>geFloat#</literal></primary></indexterm>
+<indexterm><primary><literal>eqFloat#</literal></primary></indexterm>
+<indexterm><primary><literal>neFloat#</literal></primary></indexterm>
+<indexterm><primary><literal>ltFloat#</literal></primary></indexterm>
+<indexterm><primary><literal>leFloat#</literal></primary></indexterm>
+<indexterm><primary><literal>negateFloat#</literal></primary></indexterm>
+<indexterm><primary><literal>float2Int#</literal></primary></indexterm>
+<indexterm><primary><literal>int2Float#</literal></primary></indexterm>
+</para>
+
+<para>
+And a full complement of trigonometric functions:
+</para>
+
+<para>
+
+<programlisting>
+expDouble# :: Double# -> Double#
+logDouble# :: Double# -> Double#
+sqrtDouble# :: Double# -> Double#
+sinDouble# :: Double# -> Double#
+cosDouble# :: Double# -> Double#
+tanDouble# :: Double# -> Double#
+asinDouble# :: Double# -> Double#
+acosDouble# :: Double# -> Double#
+atanDouble# :: Double# -> Double#
+sinhDouble# :: Double# -> Double#
+coshDouble# :: Double# -> Double#
+tanhDouble# :: Double# -> Double#
+powerDouble# :: Double# -> Double# -> Double#
+</programlisting>
+
+<indexterm><primary>trigonometric functions, primitive</primary></indexterm>
+</para>
+
+<para>
+similarly for <literal>Float#</literal>.
+</para>
+
+<para>
+There are two coercion functions for <literal>Float#</literal>/<literal>Double#</literal>:
+</para>
+
+<para>
+
+<programlisting>
+float2Double# :: Float# -> Double#
+double2Float# :: Double# -> Float#
+</programlisting>
+
+<indexterm><primary><literal>float2Double#</literal></primary></indexterm>
+<indexterm><primary><literal>double2Float#</literal></primary></indexterm>
+</para>
+
+<para>
+The primitive version of <function>decodeDouble</function>
+(<function>encodeDouble</function> is implemented as an external C
+function):
+</para>
+
+<para>
+
+<programlisting>
+decodeDouble# :: Double# -> PrelNum.ReturnIntAndGMP
+</programlisting>
+
+<indexterm><primary><literal>encodeDouble#</literal></primary></indexterm>
+<indexterm><primary><literal>decodeDouble#</literal></primary></indexterm>
+</para>
+
+<para>
+(And the same for <literal>Float#</literal>s.)
+</para>
+
+</sect2>
+
+<sect2 id="integer-operations">
+<title>Operations on/for <literal>Integers</literal> (interface to GMP)
+</title>
+
+<para>
+<indexterm><primary>arbitrary precision integers</primary></indexterm>
+<indexterm><primary>Integer, operations on</primary></indexterm>
+</para>
+
+<para>
+We implement <literal>Integers</literal> (arbitrary-precision
+integers) using the GNU multiple-precision (GMP) package (version
+2.0.2).
+</para>
+
+<para>
+The data type for <literal>Integer</literal> is either a small
+integer, represented by an <literal>Int</literal>, or a large integer
+represented using the pieces required by GMP's
+<literal>MP_INT</literal> in <filename>gmp.h</filename> (see
+<filename>gmp.info</filename> in
+<filename>ghc/includes/runtime/gmp</filename>). It comes out as:
+</para>
+
+<para>
+
+<programlisting>
+data Integer = S# Int# -- small integers
+ | J# Int# ByteArray# -- large integers
+</programlisting>
+
+<indexterm><primary>Integer type</primary></indexterm> The primitive
+ops to support large <literal>Integers</literal> use the
+“pieces” of the representation, and are as follows:
+</para>
+
+<para>
+
+<programlisting>
+negateInteger# :: Int# -> ByteArray# -> Integer
+
+{plus,minus,times}Integer#, gcdInteger#,
+ quotInteger#, remInteger#, divExactInteger#
+ :: Int# -> ByteArray#
+ -> Int# -> ByteArray#
+ -> (# Int#, ByteArray# #)
+
+cmpInteger#
+ :: Int# -> ByteArray#
+ -> Int# -> ByteArray#
+ -> Int# -- -1 for <; 0 for ==; +1 for >
+
+cmpIntegerInt#
+ :: Int# -> ByteArray#
+ -> Int#
+ -> Int# -- -1 for <; 0 for ==; +1 for >
+
+gcdIntegerInt# ::
+ :: Int# -> ByteArray#
+ -> Int#
+ -> Int#
+
+divModInteger#, quotRemInteger#
+ :: Int# -> ByteArray#
+ -> Int# -> ByteArray#
+ -> (# Int#, ByteArray#,
+ Int#, ByteArray# #)
+
+integer2Int# :: Int# -> ByteArray# -> Int#
+
+int2Integer# :: Int# -> Integer -- NB: no error-checking on these two!
+word2Integer# :: Word# -> Integer
+
+addr2Integer# :: Addr# -> Integer
+ -- the Addr# is taken to be a `char *' string
+ -- to be converted into an Integer.
+</programlisting>
+
+<indexterm><primary><literal>negateInteger#</literal></primary></indexterm>
+<indexterm><primary><literal>plusInteger#</literal></primary></indexterm>
+<indexterm><primary><literal>minusInteger#</literal></primary></indexterm>
+<indexterm><primary><literal>timesInteger#</literal></primary></indexterm>
+<indexterm><primary><literal>quotInteger#</literal></primary></indexterm>
+<indexterm><primary><literal>remInteger#</literal></primary></indexterm>
+<indexterm><primary><literal>gcdInteger#</literal></primary></indexterm>
+<indexterm><primary><literal>gcdIntegerInt#</literal></primary></indexterm>
+<indexterm><primary><literal>divExactInteger#</literal></primary></indexterm>
+<indexterm><primary><literal>cmpInteger#</literal></primary></indexterm>
+<indexterm><primary><literal>divModInteger#</literal></primary></indexterm>
+<indexterm><primary><literal>quotRemInteger#</literal></primary></indexterm>
+<indexterm><primary><literal>integer2Int#</literal></primary></indexterm>
+<indexterm><primary><literal>int2Integer#</literal></primary></indexterm>
+<indexterm><primary><literal>word2Integer#</literal></primary></indexterm>
+<indexterm><primary><literal>addr2Integer#</literal></primary></indexterm>
+</para>
+
+</sect2>
+
+<sect2>
+<title>Words and addresses</title>
+
+<para>
+<indexterm><primary>word, primitive type</primary></indexterm>
+<indexterm><primary>address, primitive type</primary></indexterm>
+<indexterm><primary>unsigned integer, primitive type</primary></indexterm>
+<indexterm><primary>pointer, primitive type</primary></indexterm>
+</para>
+
+<para>
+A <literal>Word#</literal> is used for bit-twiddling operations.
+It is the same size as an <literal>Int#</literal>, but has no sign
+nor any arithmetic operations.
+
+<programlisting>
+type Word# -- Same size/etc as Int# but *unsigned*
+type Addr# -- A pointer from outside the "Haskell world" (from C, probably);
+ -- described under "arrays"
+</programlisting>
+
+<indexterm><primary><literal>Word#</literal></primary></indexterm>
+<indexterm><primary><literal>Addr#</literal></primary></indexterm>
+</para>
+
+<para>
+<literal>Word#</literal>s and <literal>Addr#</literal>s have
+the usual comparison operations. Other
+unboxed-<literal>Word</literal> ops (bit-twiddling and coercions):
+</para>
+
+<para>
+
+<programlisting>
+{gt,ge,eq,ne,lt,le}Word# :: Word# -> Word# -> Bool
+
+and#, or#, xor# :: Word# -> Word# -> Word#
+ -- standard bit ops.
+
+quotWord#, remWord# :: Word# -> Word# -> Word#
+ -- word (i.e. unsigned) versions are different from int
+ -- versions, so we have to provide these explicitly.
+
+not# :: Word# -> Word#
+
+shiftL#, shiftRL# :: Word# -> Int# -> Word#
+ -- shift left, right logical
+
+int2Word# :: Int# -> Word# -- just a cast, really
+word2Int# :: Word# -> Int#
+</programlisting>
+
+<indexterm><primary>bit operations, Word and Addr</primary></indexterm>
+<indexterm><primary><literal>gtWord#</literal></primary></indexterm>
+<indexterm><primary><literal>geWord#</literal></primary></indexterm>
+<indexterm><primary><literal>eqWord#</literal></primary></indexterm>
+<indexterm><primary><literal>neWord#</literal></primary></indexterm>
+<indexterm><primary><literal>ltWord#</literal></primary></indexterm>
+<indexterm><primary><literal>leWord#</literal></primary></indexterm>
+<indexterm><primary><literal>and#</literal></primary></indexterm>
+<indexterm><primary><literal>or#</literal></primary></indexterm>
+<indexterm><primary><literal>xor#</literal></primary></indexterm>
+<indexterm><primary><literal>not#</literal></primary></indexterm>
+<indexterm><primary><literal>quotWord#</literal></primary></indexterm>
+<indexterm><primary><literal>remWord#</literal></primary></indexterm>
+<indexterm><primary><literal>shiftL#</literal></primary></indexterm>
+<indexterm><primary><literal>shiftRA#</literal></primary></indexterm>
+<indexterm><primary><literal>shiftRL#</literal></primary></indexterm>
+<indexterm><primary><literal>int2Word#</literal></primary></indexterm>
+<indexterm><primary><literal>word2Int#</literal></primary></indexterm>
+</para>
+
+<para>
+Unboxed-<literal>Addr</literal> ops (C casts, really):
+
+<programlisting>
+{gt,ge,eq,ne,lt,le}Addr# :: Addr# -> Addr# -> Bool
+
+int2Addr# :: Int# -> Addr#
+addr2Int# :: Addr# -> Int#
+addr2Integer# :: Addr# -> (# Int#, ByteArray# #)
+</programlisting>
+
+<indexterm><primary><literal>gtAddr#</literal></primary></indexterm>
+<indexterm><primary><literal>geAddr#</literal></primary></indexterm>
+<indexterm><primary><literal>eqAddr#</literal></primary></indexterm>
+<indexterm><primary><literal>neAddr#</literal></primary></indexterm>
+<indexterm><primary><literal>ltAddr#</literal></primary></indexterm>
+<indexterm><primary><literal>leAddr#</literal></primary></indexterm>
+<indexterm><primary><literal>int2Addr#</literal></primary></indexterm>
+<indexterm><primary><literal>addr2Int#</literal></primary></indexterm>
+<indexterm><primary><literal>addr2Integer#</literal></primary></indexterm>
+</para>
+
+<para>
+The casts between <literal>Int#</literal>,
+<literal>Word#</literal> and <literal>Addr#</literal>
+correspond to null operations at the machine level, but are required
+to keep the Haskell type checker happy.
+</para>
+
+<para>
+Operations for indexing off of C pointers
+(<literal>Addr#</literal>s) to snatch values are listed under
+“arrays”.
+</para>
+
+</sect2>
+
+<sect2>
+<title>Arrays</title>
+
+<para>
+<indexterm><primary>arrays, primitive</primary></indexterm>
+</para>
+
+<para>
+The type <literal>Array# elt</literal> is the type of primitive,
+unpointed arrays of values of type <literal>elt</literal>.
+</para>
+
+<para>
+
+<programlisting>
+type Array# elt
+</programlisting>
+
+<indexterm><primary><literal>Array#</literal></primary></indexterm>
+</para>
+
+<para>
+<literal>Array#</literal> is more primitive than a Haskell
+array—indeed, the Haskell <literal>Array</literal> interface is
+implemented using <literal>Array#</literal>—in that an
+<literal>Array#</literal> is indexed only by
+<literal>Int#</literal>s, starting at zero. It is also more
+primitive by virtue of being unboxed. That doesn't mean that it isn't
+a heap-allocated object—of course, it is. Rather, being unboxed
+means that it is represented by a pointer to the array itself, and not
+to a thunk which will evaluate to the array (or to bottom). The
+components of an <literal>Array#</literal> are themselves boxed.
+</para>
+
+<para>
+The type <literal>ByteArray#</literal> is similar to
+<literal>Array#</literal>, except that it contains just a string
+of (non-pointer) bytes.
+</para>
+
+<para>
+
+<programlisting>
+type ByteArray#
+</programlisting>
+
+<indexterm><primary><literal>ByteArray#</literal></primary></indexterm>
+</para>
+
+<para>
+Arrays of these types are useful when a Haskell program wishes to
+construct a value to pass to a C procedure. It is also possible to use
+them to build (say) arrays of unboxed characters for internal use in a
+Haskell program. Given these uses, <literal>ByteArray#</literal>
+is deliberately a bit vague about the type of its components.
+Operations are provided to extract values of type
+<literal>Char#</literal>, <literal>Int#</literal>,
+<literal>Float#</literal>, <literal>Double#</literal>, and
+<literal>Addr#</literal> from arbitrary offsets within a
+<literal>ByteArray#</literal>. (For type
+<literal>Foo#</literal>, the $i$th offset gets you the $i$th
+<literal>Foo#</literal>, not the <literal>Foo#</literal> at
+byte-position $i$. Mumble.) (If you want a
+<literal>Word#</literal>, grab an <literal>Int#</literal>,
+then coerce it.)
+</para>
+
+<para>
+Lastly, we have static byte-arrays, of type
+<literal>Addr#</literal> [mentioned previously]. (Remember
+the duality between arrays and pointers in C.) Arrays of this types
+are represented by a pointer to an array in the world outside Haskell,
+so this pointer is not followed by the garbage collector. In other
+respects they are just like <literal>ByteArray#</literal>. They
+are only needed in order to pass values from C to Haskell.
+</para>
+
+</sect2>
+
+<sect2>
+<title>Reading and writing</title>
+
+<para>
+Primitive arrays are linear, and indexed starting at zero.
+</para>
+
+<para>
+The size and indices of a <literal>ByteArray#</literal>, <literal>Addr#</literal>, and
+<literal>MutableByteArray#</literal> are all in bytes. It's up to the program to
+calculate the correct byte offset from the start of the array. This
+allows a <literal>ByteArray#</literal> to contain a mixture of values of different
+type, which is often needed when preparing data for and unpicking
+results from C. (Umm…not true of indices…WDP 95/09)
+</para>
+
+<para>
+<emphasis>Should we provide some <literal>sizeOfDouble#</literal> constants?</emphasis>
+</para>
+
+<para>
+Out-of-range errors on indexing should be caught by the code which
+uses the primitive operation; the primitive operations themselves do
+<emphasis>not</emphasis> check for out-of-range indexes. The intention is that the
+primitive ops compile to one machine instruction or thereabouts.
+</para>
+
+<para>
+We use the terms “reading” and “writing” to refer to accessing
+<emphasis>mutable</emphasis> arrays (see <xref LinkEnd="sect-mutable">), and
+“indexing” to refer to reading a value from an <emphasis>immutable</emphasis>
+array.
+</para>
+
+<para>
+Immutable byte arrays are straightforward to index (all indices in bytes):
+
+<programlisting>
+indexCharArray# :: ByteArray# -> Int# -> Char#
+indexIntArray# :: ByteArray# -> Int# -> Int#
+indexAddrArray# :: ByteArray# -> Int# -> Addr#
+indexFloatArray# :: ByteArray# -> Int# -> Float#
+indexDoubleArray# :: ByteArray# -> Int# -> Double#
+
+indexCharOffAddr# :: Addr# -> Int# -> Char#
+indexIntOffAddr# :: Addr# -> Int# -> Int#
+indexFloatOffAddr# :: Addr# -> Int# -> Float#
+indexDoubleOffAddr# :: Addr# -> Int# -> Double#
+indexAddrOffAddr# :: Addr# -> Int# -> Addr#
+ -- Get an Addr# from an Addr# offset
+</programlisting>
+
+<indexterm><primary><literal>indexCharArray#</literal></primary></indexterm>
+<indexterm><primary><literal>indexIntArray#</literal></primary></indexterm>
+<indexterm><primary><literal>indexAddrArray#</literal></primary></indexterm>
+<indexterm><primary><literal>indexFloatArray#</literal></primary></indexterm>
+<indexterm><primary><literal>indexDoubleArray#</literal></primary></indexterm>
+<indexterm><primary><literal>indexCharOffAddr#</literal></primary></indexterm>
+<indexterm><primary><literal>indexIntOffAddr#</literal></primary></indexterm>
+<indexterm><primary><literal>indexFloatOffAddr#</literal></primary></indexterm>
+<indexterm><primary><literal>indexDoubleOffAddr#</literal></primary></indexterm>
+<indexterm><primary><literal>indexAddrOffAddr#</literal></primary></indexterm>
+</para>
+
+<para>
+The last of these, <function>indexAddrOffAddr#</function>, extracts an <literal>Addr#</literal> using an offset
+from another <literal>Addr#</literal>, thereby providing the ability to follow a chain of
+C pointers.
+</para>
+
+<para>
+Something a bit more interesting goes on when indexing arrays of boxed
+objects, because the result is simply the boxed object. So presumably
+it should be entered—we never usually return an unevaluated
+object! This is a pain: primitive ops aren't supposed to do
+complicated things like enter objects. The current solution is to
+return a single element unboxed tuple (see <xref LinkEnd="unboxed-tuples">).
+</para>
+
+<para>
+
+<programlisting>
+indexArray# :: Array# elt -> Int# -> (# elt #)
+</programlisting>
+
+<indexterm><primary><literal>indexArray#</literal></primary></indexterm>
+</para>
+
+</sect2>
+
+<sect2>
+<title>The state type</title>
+
+<para>
+<indexterm><primary><literal>state, primitive type</literal></primary></indexterm>
+<indexterm><primary><literal>State#</literal></primary></indexterm>
+</para>
+
+<para>
+The primitive type <literal>State#</literal> represents the state of a state
+transformer. It is parameterised on the desired type of state, which
+serves to keep states from distinct threads distinct from one another.
+But the <emphasis>only</emphasis> effect of this parameterisation is in the type
+system: all values of type <literal>State#</literal> are represented in the same way.
+Indeed, they are all represented by nothing at all! The code
+generator “knows” to generate no code, and allocate no registers
+etc, for primitive states.
+</para>
+
+<para>
+
+<programlisting>
+type State# s
+</programlisting>
+
+</para>
+
+<para>
+The type <literal>GHC.RealWorld</literal> is truly opaque: there are no values defined
+of this type, and no operations over it. It is “primitive” in that
+sense - but it is <emphasis>not unlifted!</emphasis> Its only role in life is to be
+the type which distinguishes the <literal>IO</literal> state transformer.
+</para>
+
+<para>
+
+<programlisting>
+data RealWorld
+</programlisting>
+
+</para>
+
+</sect2>
+
+<sect2>
+<title>State of the world</title>
+
+<para>
+A single, primitive, value of type <literal>State# RealWorld</literal> is provided.
+</para>
+
+<para>
+
+<programlisting>
+realWorld# :: State# RealWorld
+</programlisting>
+
+<indexterm><primary>realWorld# state object</primary></indexterm>
+</para>
+
+<para>
+(Note: in the compiler, not a <literal>PrimOp</literal>; just a mucho magic
+<literal>Id</literal>. Exported from <literal>GHC</literal>, though).
+</para>
+
+</sect2>
+
+<sect2 id="sect-mutable">
+<title>Mutable arrays</title>
+
+<para>
+<indexterm><primary>mutable arrays</primary></indexterm>
+<indexterm><primary>arrays, mutable</primary></indexterm>
+Corresponding to <literal>Array#</literal> and <literal>ByteArray#</literal>, we have the types of
+mutable versions of each. In each case, the representation is a
+pointer to a suitable block of (mutable) heap-allocated storage.
+</para>
+
+<para>
+
+<programlisting>
+type MutableArray# s elt
+type MutableByteArray# s
+</programlisting>
+
+<indexterm><primary><literal>MutableArray#</literal></primary></indexterm>
+<indexterm><primary><literal>MutableByteArray#</literal></primary></indexterm>
+</para>
+
+<sect3>
+<title>Allocation</title>
+
+<para>
+<indexterm><primary>mutable arrays, allocation</primary></indexterm>
+<indexterm><primary>arrays, allocation</primary></indexterm>
+<indexterm><primary>allocation, of mutable arrays</primary></indexterm>
+</para>
+
+<para>
+Mutable arrays can be allocated. Only pointer-arrays are initialised;
+arrays of non-pointers are filled in by “user code” rather than by
+the array-allocation primitive. Reason: only the pointer case has to
+worry about GC striking with a partly-initialised array.
+</para>
+
+<para>
+
+<programlisting>
+newArray# :: Int# -> elt -> State# s -> (# State# s, MutableArray# s elt #)
+
+newCharArray# :: Int# -> State# s -> (# State# s, MutableByteArray# s elt #)
+newIntArray# :: Int# -> State# s -> (# State# s, MutableByteArray# s elt #)
+newAddrArray# :: Int# -> State# s -> (# State# s, MutableByteArray# s elt #)
+newFloatArray# :: Int# -> State# s -> (# State# s, MutableByteArray# s elt #)
+newDoubleArray# :: Int# -> State# s -> (# State# s, MutableByteArray# s elt #)
+</programlisting>
+
+<indexterm><primary><literal>newArray#</literal></primary></indexterm>
+<indexterm><primary><literal>newCharArray#</literal></primary></indexterm>
+<indexterm><primary><literal>newIntArray#</literal></primary></indexterm>
+<indexterm><primary><literal>newAddrArray#</literal></primary></indexterm>
+<indexterm><primary><literal>newFloatArray#</literal></primary></indexterm>
+<indexterm><primary><literal>newDoubleArray#</literal></primary></indexterm>
+</para>
+
+<para>
+The size of a <literal>ByteArray#</literal> is given in bytes.
+</para>
+
+</sect3>
+
+<sect3>
+<title>Reading and writing</title>
+
+<para>
+<indexterm><primary>arrays, reading and writing</primary></indexterm>
+</para>
+
+<para>
+
+<programlisting>
+readArray# :: MutableArray# s elt -> Int# -> State# s -> (# State# s, elt #)
+readCharArray# :: MutableByteArray# s -> Int# -> State# s -> (# State# s, Char# #)
+readIntArray# :: MutableByteArray# s -> Int# -> State# s -> (# State# s, Int# #)
+readAddrArray# :: MutableByteArray# s -> Int# -> State# s -> (# State# s, Addr# #)
+readFloatArray# :: MutableByteArray# s -> Int# -> State# s -> (# State# s, Float# #)
+readDoubleArray# :: MutableByteArray# s -> Int# -> State# s -> (# State# s, Double# #)
+
+writeArray# :: MutableArray# s elt -> Int# -> elt -> State# s -> State# s
+writeCharArray# :: MutableByteArray# s -> Int# -> Char# -> State# s -> State# s
+writeIntArray# :: MutableByteArray# s -> Int# -> Int# -> State# s -> State# s
+writeAddrArray# :: MutableByteArray# s -> Int# -> Addr# -> State# s -> State# s
+writeFloatArray# :: MutableByteArray# s -> Int# -> Float# -> State# s -> State# s
+writeDoubleArray# :: MutableByteArray# s -> Int# -> Double# -> State# s -> State# s
+</programlisting>
+
+<indexterm><primary><literal>readArray#</literal></primary></indexterm>
+<indexterm><primary><literal>readCharArray#</literal></primary></indexterm>
+<indexterm><primary><literal>readIntArray#</literal></primary></indexterm>
+<indexterm><primary><literal>readAddrArray#</literal></primary></indexterm>
+<indexterm><primary><literal>readFloatArray#</literal></primary></indexterm>
+<indexterm><primary><literal>readDoubleArray#</literal></primary></indexterm>
+<indexterm><primary><literal>writeArray#</literal></primary></indexterm>
+<indexterm><primary><literal>writeCharArray#</literal></primary></indexterm>
+<indexterm><primary><literal>writeIntArray#</literal></primary></indexterm>
+<indexterm><primary><literal>writeAddrArray#</literal></primary></indexterm>
+<indexterm><primary><literal>writeFloatArray#</literal></primary></indexterm>
+<indexterm><primary><literal>writeDoubleArray#</literal></primary></indexterm>
+</para>
+
+</sect3>
+
+<sect3>
+<title>Equality</title>
+
+<para>
+<indexterm><primary>arrays, testing for equality</primary></indexterm>
+</para>
+
+<para>
+One can take “equality” of mutable arrays. What is compared is the
+<emphasis>name</emphasis> or reference to the mutable array, not its contents.
+</para>
+
+<para>
+
+<programlisting>
+sameMutableArray# :: MutableArray# s elt -> MutableArray# s elt -> Bool
+sameMutableByteArray# :: MutableByteArray# s -> MutableByteArray# s -> Bool
+</programlisting>
+
+<indexterm><primary><literal>sameMutableArray#</literal></primary></indexterm>
+<indexterm><primary><literal>sameMutableByteArray#</literal></primary></indexterm>
+</para>
+
+</sect3>
+
+<sect3>
+<title>Freezing mutable arrays</title>
+
+<para>
+<indexterm><primary>arrays, freezing mutable</primary></indexterm>
+<indexterm><primary>freezing mutable arrays</primary></indexterm>
+<indexterm><primary>mutable arrays, freezing</primary></indexterm>
+</para>
+
+<para>
+Only unsafe-freeze has a primitive. (Safe freeze is done directly in Haskell
+by copying the array and then using <function>unsafeFreeze</function>.)
+</para>
+
+<para>
+
+<programlisting>
+unsafeFreezeArray# :: MutableArray# s elt -> State# s -> (# State# s, Array# s elt #)
+unsafeFreezeByteArray# :: MutableByteArray# s -> State# s -> (# State# s, ByteArray# #)
+</programlisting>
+
+<indexterm><primary><literal>unsafeFreezeArray#</literal></primary></indexterm>
+<indexterm><primary><literal>unsafeFreezeByteArray#</literal></primary></indexterm>
+</para>
+
+</sect3>
+
+</sect2>
+
+<sect2>
+<title>Synchronizing variables (M-vars)</title>
+
+<para>
+<indexterm><primary>synchronising variables (M-vars)</primary></indexterm>
+<indexterm><primary>M-Vars</primary></indexterm>
+</para>
+
+<para>
+Synchronising variables are the primitive type used to implement
+Concurrent Haskell's MVars (see the Concurrent Haskell paper for
+the operational behaviour of these operations).
+</para>
+
+<para>
+
+<programlisting>
+type MVar# s elt -- primitive
+
+newMVar# :: State# s -> (# State# s, MVar# s elt #)
+takeMVar# :: SynchVar# s elt -> State# s -> (# State# s, elt #)
+putMVar# :: SynchVar# s elt -> State# s -> State# s
+</programlisting>
+
+<indexterm><primary><literal>SynchVar#</literal></primary></indexterm>
+<indexterm><primary><literal>newSynchVar#</literal></primary></indexterm>
+<indexterm><primary><literal>takeMVar</literal></primary></indexterm>
+<indexterm><primary><literal>putMVar</literal></primary></indexterm>
+</para>
+
+</sect2>
+
+</sect1>
+
+<!-- Emacs stuff:
+ ;;; Local Variables: ***
+ ;;; mode: sgml ***
+ ;;; sgml-parent-document: ("users_guide.sgml" "book" "chapter" "sect1") ***
+ ;;; End: ***
+ -->
projects / ghc-hetmet.git / blobdiff