A Strategy is a function that embodies a parallel evaluation strategy. The function traverses (parts of) its argument, evaluating subexpressions in parallel or in sequence.

A Strategy may do an arbitrary amount of evaluation of its argument, but should not return a value different from the one it was passed.

Parallel computations may be discarded by the runtime system if the program no longer requires their result, which is why a Strategy function returns a new value equivalent to the old value. The intention is that the program applies the Strategy to a structure, and then uses the returned value, discarding the old value. This idiom is expressed by the using function.

Evaluate a value using the given Strategy.

x `using` s = runEval (s x)

evaluate a value using the given Strategy. This is simply using with the arguments reversed.

Evaluate a value using the given Strategy inside the IO monad. See also runEvalIO.

x `usingIO` s = runEvalIO (s x)

Evaluate a value using the given Strategy inside the IO monad. This is simply usingIO with the arguments reversed.

Compose two strategies sequentially. This is the analogue to function composition on strategies.

For any strategies strat1, strat2, and strat3,

(strat1 `dot` strat2) `dot` strat3 == strat1 `dot` (strat2 `dot` strat3)
strat1 `dot` strat1 = strat1
strat1 `dot` r0 == strat1

strat2 `dot` strat1 == strat2 . withStrategy strat1

r0 performs *no* evaluation.

r0 == evalSeq Control.Seq.r0

rseq evaluates its argument to weak head normal form.

rseq == evalSeq Control.Seq.rseq

rdeepseq fully evaluates its argument.

rdeepseq == evalSeq Control.Seq.rdeepseq

rpar sparks its argument (for evaluation in parallel).

Perform a computation in parallel using a strategy.

rparWith strat x

will spark strat x. Note that rparWith strat is not the same as rpar dot strat. Specifically, rpar dot strat always sparks a computation to reduce the result of the strategic computation to WHNF, while rparWith strat need not.

rparWith r0 = r0
rparWith rpar = rpar
rparWith rseq = rpar

rparWith rpar x creates a spark that immediately creates another spark to evaluate x. We consider this equivalent to rpar because there isn't any real additional parallelism. However, it is always less efficient because there's a bit of extra work to create the first (useless) spark. Similarly, rparWith r0 creates a spark that does precisely nothing. No real parallelism is added, but there is a bit of extra work to do nothing.

Inject a sequential strategy (ie. coerce a sequential strategy to a general strategy).

Thanks to evalSeq, the type Control.Seq.Strategy a is a subtype of Strategy a.

A name for Control.Seq.Strategy, for documentation only.

Evaluate the elements of a traversable data structure according to the given strategy.

Like evalTraversable but evaluates all elements in parallel.

Evaluate each element of a list according to the given strategy. Equivalent to evalTraversable at the list type.

Evaluate each element of a list in parallel according to given strategy. Equivalent to parTraversable at the list type.

Evaluate the first n elements of a list according to the given strategy.

Like evalListN but evaluates the first n elements in parallel.

Evaluate the nth element of a list (if there is such) according to the given strategy. This nth is 0-based. For example, [1, 2, 3, 4, 5] using evalListNth 4 rseq will eval 5, not 4. The spine of the list up to the nth element is evaluated as a side effect.

Like evalListN but evaluates the nth element in parallel.

evaListSplitAt n stratPref stratSuff evaluates the prefix (of length n) of a list according to stratPref and its the suffix according to stratSuff.

Like evalListSplitAt but evaluates both sublists in parallel.

Divides a list into chunks, and applies the strategy evalList strat to each chunk in parallel.

It is expected that this function will be replaced by a more generic clustering infrastructure in the future.

If the chunk size is 1 or less, parListChunk is equivalent to parList

A combination of parList and map, encapsulating a common pattern:

parMap strat f = withStrategy (parList strat) . map f

evalBuffer is a rolling buffer strategy combinator for (lazy) lists.

evalBuffer is not as compositional as the type suggests. In fact, it evaluates list elements at least to weak head normal form, disregarding a strategy argument r0.

evalBuffer n r0 == evalBuffer n rseq

Like evalBuffer but evaluates the list elements in parallel when pushing them into the buffer.

Sequential function application. The argument is evaluated using the given strategy before it is given to the function.

Parallel function application. The argument is evaluated using the given strategy, in parallel with the function application.

Sequential function composition. The result of the second function is evaluated using the given strategy, and then given to the first function.

Parallel function composition. The result of the second function is evaluated using the given strategy, in parallel with the application of the first function.

Sequential inverse function composition, for those who read their programs from left to right. The result of the first function is evaluated using the given strategy, and then given to the second function.

Parallel inverse function composition, for those who read their programs from left to right. The result of the first function is evaluated using the given strategy, in parallel with the application of the second function.

Eval is a Monad that makes it easier to define parallel strategies. It is a strict identity monad: that is, in

m >>= f

m is evaluated before the result is passed to f.

instance Monad Eval where
  return  = Done
  m >>= k = case m of
              Done x -> k x

If you wanted to construct a Strategy for a pair that sparked the first component in parallel and then evaluated the second component, you could write

myStrat :: Strategy (a,b)
myStrat (a,b) = do { a' <- rpar a; b' <- rseq b; return (a',b') }

Alternatively, you could write this more compactly using the Applicative style as

myStrat (a,b) = (,) <$> rpar a <*> rseq b

parEval sparks the computation of its argument for evaluation in parallel. Unlike rpar . runEval, parEval

• does not exit the Eval monad
• does not have a built-in rseq, so for example parEval (r0 x) behaves as you might expect (it creates a spark that does no evaluation).

It is related to rparWith by the following equality:

parEval . strat = rparWith strat

Pull the result out of the monad.

Run the evaluation in the IO monad. This allows sequencing of evaluations relative to IO actions.

DEPRECCATED: replaced by the Eval monad

DEPRECATED: Use pseq or $| instead

DEPRECATED: Use par or $|| instead

DEPRECATED: Use pseq or $| instead

DEPRECATED: Use par or $|| instead

DEPRECATED: renamed to rseq

DEPRECATED: renamed to runEval

DEPRECATED: renamed to evalTraversable

DEPRECATED: renamed to parTraversable

DEPRECATED: renamed to evalList

DEPRECATED: renamed to evalTuple2

DEPRECATED: renamed to parTuple2

DEPRECATED: renamed to evalTuple3

DEPRECATED: renamed to parTuple3

A class of types that can be fully evaluated.

Since: deepseq-1.1.0.0