[[project @ 2003-11-27 13:27:11 by simonmar]
simonmar**20031127132711
Document UNPACK pragma
] {
hunk ./ghc/docs/users_guide/glasgow_exts.sgml 4250
+
+ UNPACK pragma
hunk ./ghc/docs/users_guide/glasgow_exts.sgml 4253
+ UNPACK
+
+ There is another use for the UNPACK
+ 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:
+
+
+data T = T {-# UNPACK #-} !Float
+ {-# UNPACK #-} !Float
+
+
+ will create a constructor T containing
+ two unboxed floats. 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).
+
+ Unpacking constructor fields should only be used in
+ conjunction with , in order to expose
+ unfoldings to the compiler so the reboxing can be removed as
+ often as possible. For example:
+
+
+f :: T -> Float
+f (T f1 f2) = f1 + f2
+
+
+ The compiler will avoid reboxing f1
+ and f2 by inlining +
+ on floats, but only when is on.
+
+ Any single-constructor data is eligible for unpacking; for
+ example
+
+
+data T = T {-# UNPACK #-} !(Int,Int)
+
+
+ will store the two Ints directly in the
+ T constructor, by flattening the pair.
+ Multi-level unpacking is also supported:
+
+
+data T = T {-# UNPACK #-} !S
+data S = S {-# UNPACK #-} !Int {-# UNPACK #-} !Int
+
+
+ will store two unboxed Int#s
+ directly in the T constructor.
+
+ See also the flag,
+ which essentially has the effect of adding
+ {-# UNPACK #-} to every strict
+ constructor field.
+
hunk ./ghc/docs/users_guide/using.sgml 1188
- unpacked if possible. For example:
+ unpacked if possible. It is equivalent to adding an
+ UNPACK pragma to every strict
+ constructor field (see ).
hunk ./ghc/docs/users_guide/using.sgml 1193
-
-data T = T !Float !Float
-
-
- will create a constructor T
- containing two unboxed floats if the
- 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
- , in order to expose unfoldings to the
- compiler so the reboxing can be removed as often as
- possible. For example:
-
-
-f :: T -> Float
-f (T f1 f2) = f1 + f2
-
-
- The compiler will avoid reboxing
- f1 and f2 by
- inlining + on floats, but only when
- is on.
-
- Any single-constructor data is eligible for
- unpacking; for example
-
-
-data T = T !(Int,Int)
-
-
- will store the two Ints directly
- in the T constructor, by flattening
- the pair. Multi-level unpacking is also supported:
-
-
-data T = T !S
-data S = S !Int !Int
-
-
- will store two unboxed Int#s
- directly in the T constructor.
+ This option is a bit of a sledgehammer: it might
+ sometimes make things worse. Selectively unboxing fields
+ by using UNPACK pragmas might be
+ better.
}