From f3ecd3c3370530a5fa415c67f4bffcfc45f5951b Mon Sep 17 00:00:00 2001
From: simonm <unknown>
Date: Tue, 6 Apr 1999 09:48:01 +0000
Subject: [PATCH] [project @ 1999-04-06 09:48:01 by simonm] Document
 -funbox-strict-fields.

---
 ghc/docs/users_guide/4-03-notes.vsgml |    3 +++
 ghc/docs/users_guide/using.vsgml      |   46 +++++++++++++++++++++++++++++++++
 2 files changed, 49 insertions(+)

diff --git a/ghc/docs/users_guide/4-03-notes.vsgml b/ghc/docs/users_guide/4-03-notes.vsgml
index 72e3c99..1430b37 100644
--- a/ghc/docs/users_guide/4-03-notes.vsgml
+++ b/ghc/docs/users_guide/4-03-notes.vsgml
@@ -17,4 +17,7 @@ computations on small integers.  The performance of <tt/Integer/ is now
 only slightly slower than <tt/Int/ for values between <tt/minBound :: Int/
 and <tt/maxBound :: Int/.
 
+<item> Added @-funbox-strict-fields@ for unboxing/unpacking strict
+constructor fields.
+
 </itemize>
diff --git a/ghc/docs/users_guide/using.vsgml b/ghc/docs/users_guide/using.vsgml
index f8b7030..42cb002 100644
--- a/ghc/docs/users_guide/using.vsgml
+++ b/ghc/docs/users_guide/using.vsgml
@@ -1000,6 +1000,52 @@ arbitrary; they are of the ``seem to be OK'' variety.  The `8' is the
 more critical one; it's what determines how eager GHC is about
 expanding unfoldings.
 
+<tag>@-funbox-strict-fields@:</tag>
+<nidx>-funbox-strict-fields option</nidx>
+<nidx>strict constructor fields</nidx>
+<nidx>constructor fields, strict</nidx>
+
+This option causes all constructor fields which are marked strict
+(i.e. ``!'') to be unboxed or unpacked if possible.  For example:
+
+<tscreen><verb>
+data T = T !Float !Float
+</verb></tscreen>
+
+will create a constructor @T@ containing two unboxed floats if the
+@-funbox-strict-fields@ flag is given.  This may not always be an
+optimisation: if the @T@ 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).
+
+This option should only be used in conjunction with @-O@, in order to
+expose unfoldings to the compiler so the reboxing can be removed as
+often as possible.  For example:
+
+<tscreen><verb>
+f :: T -> Float
+f (T f1 f2) = f1 + f2
+</verb></tscreen>
+
+The compiler will avoid reboxing @f1@ and @f2@ by inlining @+@ on
+floats, but only when @-O@ is on.
+
+Any single-constructor data is eligible for unpacking; for example
+
+<tscreen><verb>
+data T = T !(Int,Int)
+</verb></tscreen>
+
+will store the two @Int@s directly in the @T@ constructor, by flattening
+the pair.  Multi-level unpacking is also supported:
+
+<tscreen><verb>
+data T = T !S
+data S = S !Int !Int
+</verb></tscreen>
+
+will store two unboxed @Int#@s directly in the @T@ constructor.
+
 <tag>@-fsemi-tagging@:</tag>
 This option (which <em>does not work</em> with the native-code generator)
 tells the compiler to add extra code to test for already-evaluated
-- 
1.7.10.4