-----------------------------------------------------------------------------
module Control.Parallel (
- par, seq -- re-exported
+ par, pseq,
+ seq, -- for backwards compatibility, 6.6 exported this
#if defined(__GRANSIM__)
, parGlobal, parLocal, parAt, parAtAbs, parAtRel, parAtForNow
#endif
import Prelude
#ifdef __GLASGOW_HASKELL__
-import qualified GHC.Conc ( par )
+import qualified GHC.Conc ( par, pseq )
#endif
#if defined(__GRANSIM__)
-- For now, Hugs does not support par properly.
par a b = b
#endif
+
+-- | Semantically identical to 'seq', but with a subtle operational
+-- difference: 'seq' is strict in both its arguments, so the compiler
+-- may, for example, rearrange @a `seq` b@ into @b `seq` a `seq` b@.
+-- This is normally no problem when using 'seq' to express strictness,
+-- but it can be a problem when annotating code for parallelism,
+-- because we need more control over the order of evaluation; we may
+-- want to evaluate @a@ before @b@, because we know that @b@ has
+-- already been sparked in parallel with 'par'.
+--
+-- This is why we have 'pseq'. In contrast to 'seq', 'pseq' is only
+-- strict in its first argument (as far as the compiler is concerned),
+-- which restricts the transformations that the compiler can do, and
+-- ensures that the user can retain control of the evaluation order.
+--
+pseq :: a -> b -> b
+#ifdef __GLASGOW_HASKELL__
+pseq = GHC.Conc.pseq
+#else
+pseq = seq
+#endif
-- Phil Trinder, Hans-Wolfgang Loidl, Kevin Hammond et al.
--
-#ifdef __HADDOCK__
-import Prelude
-#endif
-
-import Control.Parallel as Parallel
-import Data.Ix
+import Control.Parallel as Parallel (par, pseq)
import Data.Array
import Data.Complex
-import Data.Ratio
+
+import Prelude hiding (seq)
+import qualified Prelude (seq)
-- not a terribly portable way of getting at Ratio rep.
#ifdef __GLASGOW_HASKELL__
infixl 6 $||, $| -- strategic function application (seq and par)
infixl 9 .|, .||, -|, -|| -- strategic (inverse) function composition
+-- We need 'pseq', not the Prelude 'seq' here. See the documentation
+-- with 'pseq' in Control.Parallel.
+seq = Parallel.pseq
+
------------------------------------------------------------------------------
-- Strategy Type, Application and Semantics
------------------------------------------------------------------------------
-}
demanding, sparking :: a -> Done -> a
-demanding = flip Parallel.seq
+demanding = flip seq
sparking = flip Parallel.par
{-