[commit: ghc-prim] master: Move lazy from GHC.Base to GHC.Magic (04e62ee)

[Ian Lynagh]

Repository : ssh://darcs.haskell.org//srv/darcs/packages/ghc-prim

On branch  : master

http://hackage.haskell.org/trac/ghc/changeset/04e62ee51eeeb6214fa3f2e7f354028ebafa6136

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

commit 04e62ee51eeeb6214fa3f2e7f354028ebafa6136
Author: Ian Lynagh <ian at well-typed.com>
Date:   Tue Nov 13 20:48:00 2012 +0000

    Move lazy from GHC.Base to GHC.Magic

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

 GHC/Magic.hs |   28 +++++++++++++++++++++++++++-
 1 files changed, 27 insertions(+), 1 deletions(-)

diff --git a/GHC/Magic.hs b/GHC/Magic.hs
index 969067f..f616343 100644
--- a/GHC/Magic.hs
+++ b/GHC/Magic.hs
@@ -17,7 +17,7 @@
 --
 -----------------------------------------------------------------------------
 
-module GHC.Magic ( inline ) where
+module GHC.Magic ( inline, lazy ) where
 
 -- | The call '(inline f)' arranges that 'f' is inlined, regardless of
 -- its size. More precisely, the call '(inline f)' rewrites to the
@@ -38,3 +38,29 @@ module GHC.Magic ( inline ) where
 inline :: a -> a
 inline x = x
 
+-- | The 'lazy' function restrains strictness analysis a little. The
+-- call '(lazy e)' means the same as 'e', but 'lazy' has a magical
+-- property so far as strictness analysis is concerned: it is lazy in
+-- its first argument, even though its semantics is strict. After
+-- strictness analysis has run, calls to 'lazy' are inlined to be the
+-- identity function.
+--
+-- This behaviour is occasionally useful when controlling evaluation
+-- order. Notably, 'lazy' is used in the library definition of
+-- 'Control.Parallel.par':
+--
+-- > par :: a -> b -> b
+-- > par x y = case (par# x) of _ -> lazy y
+--
+-- If 'lazy' were not lazy, 'par' would look strict in 'y' which
+-- would defeat the whole purpose of 'par'.
+--
+-- Like 'seq', the argument of 'lazy' can have an unboxed type.
+lazy :: a -> a
+lazy x = x
+-- Implementation note: its strictness and unfolding are over-ridden
+-- by the definition in MkId.lhs; in both cases to nothing at all.
+-- That way, 'lazy' does not get inlined, and the strictness analyser
+-- sees it as lazy.  Then the worker/wrapper phase inlines it.
+-- Result: happiness
+