[project @ 2003-11-27 13:27:11 by simonmar]

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

diff --git a/ghc/docs/users_guide/glasgow_exts.sgml b/ghc/docs/users_guide/glasgow_exts.sgml
index 63fd927..a4813b0 100644 (file)
--- a/ghc/docs/users_guide/glasgow_exts.sgml
+++ b/ghc/docs/users_guide/glasgow_exts.sgml
@@ -1435,14 +1435,14 @@ With the <option>-fglasgow-exts</option> GHC lifts this restriction.
 
 <sect3><title>The context of a type signature</title>
 <para>
-Unlike Haskell 1.4, constraints in types do <emphasis>not</emphasis> have to be of
-the form <emphasis>(class type-variables)</emphasis>.  Thus, these type signatures
-are perfectly OK
+Unlike Haskell 98, constraints in types do <emphasis>not</emphasis> have to be of
+the form <emphasis>(class type-variable)</emphasis> or
+<emphasis>(class (type-variable type-variable ...))</emphasis>.  Thus,
+these type signatures are perfectly OK
 <programlisting>
-  f :: Eq (m a) => [m a] -> [m a]
   g :: Eq [a] => ...
+  g :: Ord (T a ()) => ...
 </programlisting>
-This choice recovers principal types, a property that Haskell 1.4 does not have.
 </para>
 <para>
 GHC imposes the following restrictions on the constraints in a type signature.
@@ -1453,7 +1453,7 @@ Consider the type:
 </programlisting>
 
 (Here, we write the "foralls" explicitly, although the Haskell source
-language omits them; in Haskell 1.4, all the free type variables of an
+language omits them; in Haskell 98, all the free type variables of an
 explicit source-language type signature are universally quantified,
 except for the class type variables in a class declaration.  However,
 in GHC, you can give the foralls if you want.  See <xref LinkEnd="universal-quantification">).
@@ -1684,7 +1684,7 @@ change that decision, at least for <literal>Main</literal>.)
 <title>Type synonyms in the instance head</title>
 
 <para>
-<emphasis>Unlike Haskell 1.4, instance heads may use type
+<emphasis>Unlike Haskell 98, instance heads may use type
 synonyms</emphasis>.  (The instance "head" is the bit after the "=>" in an instance decl.)
 As always, using a type synonym is just shorthand for
 writing the RHS of the type synonym definition.  For example:
@@ -2296,8 +2296,8 @@ the <literal>forall</literal> is on the left of a function arrrow.  As <literal>
 shows, the polymorphic type on the left of the function arrow can be overloaded.
 </para>
 <para>
-The functions <literal>f3</literal> and <literal>g3</literal> have rank-3 types;
-they have rank-2 types on the left of a function arrow.
+The function <literal>f3</literal> has a rank-3 type;
+it has rank-2 types on the left of a function arrow.
 </para>
 <para>
 GHC allows types of arbitrary rank; you can nest <literal>forall</literal>s
@@ -2309,7 +2309,7 @@ including an operational type class context, is legal:
 <listitem> <para> On the left of a function arrow </para> </listitem>
 <listitem> <para> On the right of a function arrow (see <xref linkend="hoist">) </para> </listitem>
 <listitem> <para> As the argument of a constructor, or type of a field, in a data type declaration. For
-example, any of the <literal>f1,f2,f3,g1,g2,g3</literal> above would be valid
+example, any of the <literal>f1,f2,f3,g1,g2</literal> above would be valid
 field type signatures.</para> </listitem>
 <listitem> <para> As the type of an implicit parameter </para> </listitem>
 <listitem> <para> In a pattern type signature (see <xref linkend="scoped-type-variables">) </para> </listitem>
@@ -4247,7 +4247,66 @@ of the pragma.
 
 </sect2>
 
-
+    <sect2 id="unpack-pragma">
+      <title>UNPACK pragma</title>
+
+      <indexterm><primary>UNPACK</primary> </indexterm>
+      
+      <para>There is another use for the <literal>UNPACK</literal>
+      pragma: to indicate that the compiler should unpack the contents
+      of a constructor field into the constructor itself, removing a
+      level of indirection.  For example:</para>
+
+<ProgramListing>
+data T = T {-# UNPACK #-} !Float
+           {-# UNPACK #-} !Float
+</ProgramListing>
+
+      <para>will create a constructor <literal>T</literal> containing
+      two unboxed floats.  This may not always be an optimisation: if
+      the <Function>T</Function> constructor is scrutinised and the
+      floats passed to a non-strict function for example, they will
+      have to be reboxed (this is done automatically by the
+      compiler).</para>
+
+      <para>Unpacking constructor fields should only be used in
+      conjunction with <option>-O</option>, in order to expose
+      unfoldings to the compiler so the reboxing can be removed as
+      often as possible.  For example:</para>
+
+<ProgramListing>
+f :: T -&#62; Float
+f (T f1 f2) = f1 + f2
+</ProgramListing>
+
+      <para>The compiler will avoid reboxing <Function>f1</Function>
+      and <Function>f2</Function> by inlining <Function>+</Function>
+      on floats, but only when <option>-O</option> is on.</para>
+
+      <para>Any single-constructor data is eligible for unpacking; for
+      example</para>
+
+<ProgramListing>
+data T = T {-# UNPACK #-} !(Int,Int)
+</ProgramListing>
+
+      <para>will store the two <literal>Int</literal>s directly in the
+      <Function>T</Function> constructor, by flattening the pair.
+      Multi-level unpacking is also supported:</para>
+
+<ProgramListing>
+data T = T {-# UNPACK #-} !S
+data S = S {-# UNPACK #-} !Int {-# UNPACK #-} !Int
+</ProgramListing>
+
+      <para>will store two unboxed <literal>Int&num;</literal>s
+      directly in the <Function>T</Function> constructor.</para>
+
+      <para>See also the <option>-funbox-strict-fields</option> flag,
+      which essentially has the effect of adding
+      <literal>{-#&nbsp;UNPACK&nbsp;#-}</literal> to every strict
+      constructor field.</para>
+    </sect2>
 
 </sect1>