<sect1 id="primitives">
<title>Unboxed types and primitive operations</title>
- <indexterm><primary>PrelGHC module</primary></indexterm>
+ <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>PrelGHC</literal>.</para>
+ 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
</title>
<para>
-Unboxed tuples aren't really exported by <literal>PrelGHC</literal>,
+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>
double2Int# :: Double# -> Int#
int2Double# :: Int# -> Double#
-{plus,minux,times,divide}Float# :: Float# -> Float# -> Float#
+{plus,minus,times,divide}Float# :: Float# -> Float# -> Float#
{gt,ge,eq,ne,lt,le}Float# :: Float# -> Float# -> Bool
negateFloat# :: Float# -> Float#
float2Int# :: Float# -> Int#
</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: