[commit: ghc] master: Improve seq documentation; part of trac issue #9390 (cbfa107)

[git at git.haskell.org]

Repository : ssh://git@git.haskell.org/ghc

On branch  : master
Link       : http://ghc.haskell.org/trac/ghc/changeset/cbfa107604f4cbfaf02bd633c1faa6ecb90c6dd7/ghc

>---------------------------------------------------------------

commit cbfa107604f4cbfaf02bd633c1faa6ecb90c6dd7
Author: Michael Snoyman <michael at snoyman.com>
Date:   Sun Aug 10 15:54:01 2014 -0500

    Improve seq documentation; part of trac issue #9390
    
    Summary: Signed-off-by: Michael Snoyman <michael at snoyman.com>
    
    Test Plan: Review documentation change
    
    Reviewers: simonpj, austin
    
    Reviewed By: austin
    
    Subscribers: phaskell, hvr, simonmar, relrod, ezyang, carter
    
    Differential Revision: https://phabricator.haskell.org/D136
    
    GHC Trac Issues: #9390


>---------------------------------------------------------------

cbfa107604f4cbfaf02bd633c1faa6ecb90c6dd7
 libraries/base/Prelude.hs | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/libraries/base/Prelude.hs b/libraries/base/Prelude.hs
index 6be7846..9b1119e 100644
--- a/libraries/base/Prelude.hs
+++ b/libraries/base/Prelude.hs
@@ -163,6 +163,13 @@ f $! x  = let !vx = x in f vx  -- see #2273
 -- | The value of @'seq' a b@ is bottom if @a@ is bottom, and otherwise
 -- equal to @b at .  'seq' is usually introduced to improve performance by
 -- avoiding unneeded laziness.
+--
+-- A note on evaluation order: the expression @seq a b@ does /not/ guarantee
+-- that @a@ will be evaluated before @b at . The only guarantee given by @seq@ is
+-- that the both @a@ and @b@ will be evaluated before @seq@ returns a value. In
+-- particular, this means that @b@ may be evaluated before @a at . If you need to
+-- guarantee a specific order of evaluation, you must use the function @pseq@
+-- from the parallel package.
 seq :: a -> b -> b
 seq _ y = y
 #endif