-<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- UNBOXED TYPES AND PRIMITIVE OPERATIONS -->
-
-<sect1 id="primitives">
- <title>Unboxed types and primitive operations</title>
- <indexterm><primary>GHC.Exts module</primary></indexterm>
-
- <para>This chapter defines all the types which are primitive in
- Glasgow Haskell, and the operations provided for them. You bring
- them into scope by importing module <literal>GHC.Exts</literal>.</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>GHC.Exts</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,minus,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 are in
-units of the size of the object being read):
-
-<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>
-
-<sect2 id="glasgow-prim-arrays">
-<title>Primitive arrays, mutable and otherwise
-</title>
-
-<para>
-<indexterm><primary>primitive arrays (Glasgow extension)</primary></indexterm>
-<indexterm><primary>arrays, primitive (Glasgow extension)</primary></indexterm>
-</para>
-
-<para>
-GHC knows about quite a few flavours of Large Swathes of Bytes.
-</para>
-
-<para>
-First, GHC distinguishes between primitive arrays of (boxed) Haskell
-objects (type <literal>Array# obj</literal>) and primitive arrays of bytes (type
-<literal>ByteArray#</literal>).
-</para>
-
-<para>
-Second, it distinguishes between…
-<variablelist>
-
-<varlistentry>
-<term>Immutable:</term>
-<listitem>
-<para>
-Arrays that do not change (as with “standard” Haskell arrays); you
-can only read from them. Obviously, they do not need the care and
-attention of the state-transformer monad.
-</para>
-</listitem>
-</varlistentry>
-<varlistentry>
-<term>Mutable:</term>
-<listitem>
-<para>
-Arrays that may be changed or “mutated.” All the operations on them
-live within the state-transformer monad and the updates happen
-<emphasis>in-place</emphasis>.
-</para>
-</listitem>
-</varlistentry>
-<varlistentry>
-<term>“Static” (in C land):</term>
-<listitem>
-<para>
-A C routine may pass an <literal>Addr#</literal> pointer back into Haskell land. There
-are then primitive operations with which you may merrily grab values
-over in C land, by indexing off the “static” pointer.
-</para>
-</listitem>
-</varlistentry>
-<varlistentry>
-<term>“Stable” pointers:</term>
-<listitem>
-<para>
-If, for some reason, you wish to hand a Haskell pointer (i.e.,
-<emphasis>not</emphasis> an unboxed value) to a C routine, you first make the
-pointer “stable,” so that the garbage collector won't forget that it
-exists. That is, GHC provides a safe way to pass Haskell pointers to
-C.
-</para>
-
-<para>
-Please see the module <literal>Foreign.StablePtr</literal> in the
-library documentation for more details.
-</para>
-</listitem>
-</varlistentry>
-<varlistentry>
-<term>“Foreign objects”:</term>
-<listitem>
-<para>
-A “foreign object” is a safe way to pass an external object (a
-C-allocated pointer, say) to Haskell and have Haskell do the Right
-Thing when it no longer references the object. So, for example, C
-could pass a large bitmap over to Haskell and say “please free this
-memory when you're done with it.”
-</para>
-
-<para>
-Please see module <literal>Foreign.ForeignPtr</literal> in the library
-documentatation for more details.
-</para>
-</listitem>
-</varlistentry>
-</variablelist>
-</para>
-
-<para>
-The libraries documentatation gives more details on all these
-“primitive array” types and the operations on them.
-</para>
-
-</sect2>
-
-</sect1>
-
-<!-- Emacs stuff:
- ;;; Local Variables: ***
- ;;; mode: xml ***
- ;;; sgml-parent-document: ("users_guide.xml" "book" "chapter" "sect1") ***
- ;;; End: ***
- -->
projects / ghc-hetmet.git / commitdiff