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.
This module provides an overloaded function, deepseq, for fully evaluating data structures (that is, evaluating to "Normal Form").
A typical use is to prevent resource leaks in lazy IO programs, by forcing all characters from a file to be read. For example:
> import System.IO
> import Control.DeepSeq
> main = do
> h <- openFile "f" ReadMode
> s <- hGetContents h
> s `deepseq` hClose h
> return s
deepseq differs from seq as it traverses data structures deeply, for example, seq will evaluate only to the first constructor in the list:
> > [1,2,undefined] `seq` 3
While deepseq will force evaluation of all the list elements:
> > [1,2,undefined] `deepseq` 3
> *** Exception: Prelude.undefined
Another common use is to ensure any exceptions hidden within lazy fields of a data structure do not leak outside the scope of the exception handler, or to force evaluation of a data structure in one thread, before passing to another thread (preventing work moving to the wrong threads).
deepseq: fully evaluates the first argument, before returning the second.
The name deepseq is used to illustrate the relationship to seq: evaluates the top level of its argument, deepseq traverses the entire data structure evaluating it completely.
deepseq can be useful for forcing pending exceptions, eradicating space leaks, or forcing lazy I/O to happen. It is also useful in conjunction with parallel Strategies (see the parallel package).
There is no guarantee about the ordering of evaluation. The implementation may evaluate the components of the structure in any order or in parallel. To impose an actual order on evaluation, use pseq from Control.Parallel in the parallel package.
rdeepseq fully evaluates its argument.
> rdeepseq == evalSeq Control.Seq.rdeepseq