add install-includes: field
[packages/pretty.git] / Control / Parallel.hs
1 -----------------------------------------------------------------------------
2 -- |
3 -- Module : Control.Parallel
4 -- Copyright : (c) The University of Glasgow 2001
5 -- License : BSD-style (see the file libraries/base/LICENSE)
6 --
7 -- Maintainer : libraries@haskell.org
8 -- Stability : experimental
9 -- Portability : non-portable
10 --
11 -- Parallel Constructs
12 --
13 -----------------------------------------------------------------------------
14
15 module Control.Parallel (
16 par, pseq,
17 seq, -- for backwards compatibility, 6.6 exported this
18 #if defined(__GRANSIM__)
19 , parGlobal, parLocal, parAt, parAtAbs, parAtRel, parAtForNow
20 #endif
21 ) where
22
23 import Prelude
24
25 #ifdef __GLASGOW_HASKELL__
26 import qualified GHC.Conc ( par, pseq )
27 #endif
28
29 #if defined(__GRANSIM__)
30 import PrelBase
31 import PrelErr ( parError )
32 import PrelGHC ( parGlobal#, parLocal#, parAt#, parAtAbs#, parAtRel#, parAtForNow# )
33
34 infixr 0 `par`
35
36 {-# INLINE parGlobal #-}
37 {-# INLINE parLocal #-}
38 {-# INLINE parAt #-}
39 {-# INLINE parAtAbs #-}
40 {-# INLINE parAtRel #-}
41 {-# INLINE parAtForNow #-}
42 parGlobal :: Int -> Int -> Int -> Int -> a -> b -> b
43 parLocal :: Int -> Int -> Int -> Int -> a -> b -> b
44 parAt :: Int -> Int -> Int -> Int -> a -> b -> c -> c
45 parAtAbs :: Int -> Int -> Int -> Int -> Int -> a -> b -> b
46 parAtRel :: Int -> Int -> Int -> Int -> Int -> a -> b -> b
47 parAtForNow :: Int -> Int -> Int -> Int -> a -> b -> c -> c
48
49 parGlobal (I# w) (I# g) (I# s) (I# p) x y = case (parGlobal# x w g s p y) of { 0# -> parError; _ -> y }
50 parLocal (I# w) (I# g) (I# s) (I# p) x y = case (parLocal# x w g s p y) of { 0# -> parError; _ -> y }
51
52 parAt (I# w) (I# g) (I# s) (I# p) v x y = case (parAt# x v w g s p y) of { 0# -> parError; _ -> y }
53 parAtAbs (I# w) (I# g) (I# s) (I# p) (I# q) x y = case (parAtAbs# x q w g s p y) of { 0# -> parError; _ -> y }
54 parAtRel (I# w) (I# g) (I# s) (I# p) (I# q) x y = case (parAtRel# x q w g s p y) of { 0# -> parError; _ -> y }
55 parAtForNow (I# w) (I# g) (I# s) (I# p) v x y = case (parAtForNow# x v w g s p y) of { 0# -> parError; _ -> y }
56
57 #endif
58
59 -- Maybe parIO and the like could be added here later.
60
61 -- | Indicates that it may be beneficial to evaluate the first
62 -- argument in parallel with the second. Returns the value of the
63 -- second argument.
64 --
65 -- @a `par` b@ is exactly equivalent semantically to @b@.
66 --
67 -- @par@ is generally used when the value of @a@ is likely to be
68 -- required later, but not immediately. Also it is a good idea to
69 -- ensure that @a@ is not a trivial computation, otherwise the cost of
70 -- spawning it in parallel overshadows the benefits obtained by
71 -- running it in parallel.
72 --
73 -- Note that actual parallelism is only supported by certain
74 -- implementations (GHC with the @-threaded@ option, and GPH, for
75 -- now). On other implementations, @par a b = b@.
76 --
77 par :: a -> b -> b
78 #ifdef __GLASGOW_HASKELL__
79 par = GHC.Conc.par
80 #else
81 -- For now, Hugs does not support par properly.
82 par a b = b
83 #endif
84
85 -- | Semantically identical to 'seq', but with a subtle operational
86 -- difference: 'seq' is strict in both its arguments, so the compiler
87 -- may, for example, rearrange @a `seq` b@ into @b `seq` a `seq` b@.
88 -- This is normally no problem when using 'seq' to express strictness,
89 -- but it can be a problem when annotating code for parallelism,
90 -- because we need more control over the order of evaluation; we may
91 -- want to evaluate @a@ before @b@, because we know that @b@ has
92 -- already been sparked in parallel with 'par'.
93 --
94 -- This is why we have 'pseq'. In contrast to 'seq', 'pseq' is only
95 -- strict in its first argument (as far as the compiler is concerned),
96 -- which restricts the transformations that the compiler can do, and
97 -- ensures that the user can retain control of the evaluation order.
98 --
99 pseq :: a -> b -> b
100 #ifdef __GLASGOW_HASKELL__
101 pseq = GHC.Conc.pseq
102 #else
103 pseq = seq
104 #endif