[project @ 2003-11-28 10:55:59 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 af0a768..2a7f379 100644 (file)
--- a/ghc/docs/users_guide/glasgow_exts.sgml
+++ b/ghc/docs/users_guide/glasgow_exts.sgml
@@ -3781,7 +3781,7 @@ a new <literal>form</literal> keyword.
 Although only GHC implements arrow notation directly,
 there is also a preprocessor
 (available from the 
-<ulink url="http://www.haskell.org/arrows/">arrows web page></ulink>)
+<ulink url="http://www.haskell.org/arrows/">arrows web page</ulink>)
 that translates arrow notation into Haskell 98
 for use with other Haskell systems.
 You would still want to check arrow programs with GHC;
@@ -4247,7 +4247,71 @@ of the pragma.
 
 </sect2>
 
-
+    <sect2 id="unpack-pragma">
+      <title>UNPACK pragma</title>
+
+      <indexterm><primary>UNPACK</primary></indexterm>
+      
+      <para>The <literal>UNPACK</literal> indicates to the compiler
+      that it 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.  The
+      unpacker can see through newtypes, too.</para>
+
+      <para>If a field cannot be unpacked, you will not get a warning,
+      so it might be an idea to check the generated code with
+      <option>-ddump-simpl</option>.</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>