added NOUNPACK pragma (see #2338)

2 files changed, 26 insertions, 1 deletions

diff --git a/docs/users_guide/glasgow_exts.xml b/docs/users_guide/glasgow_exts.xml
index 5123e1026c..6d1b293701 100755
--- a/docs/users_guide/glasgow_exts.xml
+++ b/docs/users_guide/glasgow_exts.xml
@@ -8575,6 +8575,26 @@ data S = S {-# UNPACK #-} !Int {-# UNPACK #-} !Int
       constructor field.</para>
     </sect2>
 
+    <sect2 id="nounpack-pragma">
+      <title>NOUNPACK pragma</title>
+
+      <indexterm><primary>NOUNPACK</primary></indexterm>
+
+      <para>The <literal>NOUNPACK</literal> pragma indicates to the compiler
+      that it should not unpack the contents of a constructor field.
+      Example:
+      </para>
+<programlisting>
+data T = T {-# NOUNPACK #-} !(Int,Int)
+</programlisting>
+      <para>
+        Even with the flags
+        <option>-funbox-strict-fields</option> and <option>-O</option>,
+        the field of the constructor <function>T</function> is not
+        unpacked.
+      </para>
+    </sect2>
+
     <sect2 id="source-pragma">
       <title>SOURCE pragma</title>
 
diff --git a/docs/users_guide/using.xml b/docs/users_guide/using.xml
index eccd6f967e..4cace1ee88 100644
--- a/docs/users_guide/using.xml
+++ b/docs/users_guide/using.xml
@@ -1932,7 +1932,12 @@ f "2"    = 2
 	    <para>This option is a bit of a sledgehammer: it might
 	    sometimes make things worse.  Selectively unboxing fields
 	    by using <literal>UNPACK</literal> pragmas might be
-	    better.</para>
+	    better. An alternative is to use
+        <option>-funbox-strict-fields</option> to turn on
+        unboxing by default but disable it for certain constructor
+        fields using the <literal>NOUNPACK</literal> pragma
+        (see <xref linkend="nounpack-pragma"/>).
+        </para>
 	  </listitem>
 	</varlistentry>