From: simonmar Date: Thu, 27 Nov 2003 13:27:11 +0000 (+0000) Subject: [project @ 2003-11-27 13:27:11 by simonmar] X-Git-Tag: Approx_11550_changesets_converted~223 X-Git-Url: http://git.megacz.com/?p=ghc-hetmet.git;a=commitdiff_plain;h=fdac0d5f9911b64fa1080fbb4758d1fa0dd0070c [project @ 2003-11-27 13:27:11 by simonmar] Document UNPACK pragma --- diff --git a/ghc/docs/users_guide/glasgow_exts.sgml b/ghc/docs/users_guide/glasgow_exts.sgml index af0a768..a4813b0 100644 --- a/ghc/docs/users_guide/glasgow_exts.sgml +++ b/ghc/docs/users_guide/glasgow_exts.sgml @@ -4247,7 +4247,66 @@ of the pragma. - + + UNPACK pragma + + 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. + diff --git a/ghc/docs/users_guide/using.sgml b/ghc/docs/users_guide/using.sgml index 0abae40..fb5f6f6 100644 --- a/ghc/docs/users_guide/using.sgml +++ b/ghc/docs/users_guide/using.sgml @@ -1185,54 +1185,15 @@ f "2" = 2 This option causes all constructor fields which are marked strict (i.e. “!”) to be unboxed or - unpacked if possible. For example: - - -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. + unpacked if possible. It is equivalent to adding an + UNPACK pragma to every strict + constructor field (see ). + + This option is a bit of a sledgehammer: it might + sometimes make things worse. Selectively unboxing fields + by using UNPACK pragmas might be + better.