[project @ 2002-06-25 12:05:14 by simonmar]

[ghc-hetmet.git] / ghc / docs / users_guide / primitives.sgml

diff --git a/ghc/docs/users_guide/primitives.sgml b/ghc/docs/users_guide/primitives.sgml
index 9f2a3e3..f84794a 100644 (file)
--- a/ghc/docs/users_guide/primitives.sgml
+++ b/ghc/docs/users_guide/primitives.sgml
@@ -2,10 +2,11 @@
 
 <sect1 id="primitives">
   <title>Unboxed types and primitive operations</title>
-  <indexterm><primary>PrelGHC module</primary></indexterm>
+  <indexterm><primary>GHC.Prim module</primary></indexterm>
 
-  <para>This module defines all the types which are primitive in
-  Glasgow Haskell, and the operations provided for them.</para>
+  <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.Prim</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
@@ -92,7 +93,7 @@ counterpart&mdash;we saw a threefold speedup on one example.
 </title>
 
 <para>
-Unboxed tuples aren't really exported by <literal>PrelGHC</literal>,
+Unboxed tuples aren't really exported by <literal>GHC.Prim</literal>,
 they're available by default with <option>-fglasgow-exts</option>.  An
 unboxed tuple looks like this:
 </para>
@@ -1106,6 +1107,103 @@ putMVar#    :: SynchVar# s elt -> State# s -> State# s
 
 </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&num; obj</literal>) and primitive arrays of bytes (type
+<literal>ByteArray&num;</literal>).
+</para>
+
+<para>
+Second, it distinguishes between&hellip;
+<variablelist>
+
+<varlistentry>
+<term>Immutable:</term>
+<listitem>
+<para>
+Arrays that do not change (as with &ldquo;standard&rdquo; 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 &ldquo;mutated.&rdquo;  All the operations on them
+live within the state-transformer monad and the updates happen
+<emphasis>in-place</emphasis>.
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>&ldquo;Static&rdquo; (in C land):</term>
+<listitem>
+<para>
+A C routine may pass an <literal>Addr&num;</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 &ldquo;static&rdquo; pointer.
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>&ldquo;Stable&rdquo; 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 &ldquo;stable,&rdquo; 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>&ldquo;Foreign objects&rdquo;:</term>
+<listitem>
+<para>
+A &ldquo;foreign object&rdquo; 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 &ldquo;please free this
+memory when you're done with it.&rdquo;
+</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
+&ldquo;primitive array&rdquo; types and the operations on them.
+</para>
+
+</sect2>
+
 </sect1>
 
 <!-- Emacs stuff: