-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Deep evaluation of data structures
--   
--   This package provides methods for fully evaluating data structures
--   ("deep evaluation"). Deep evaluation is often used for adding
--   strictness to a program, e.g. in order to force pending exceptions,
--   remove space leaks, or force lazy I/O to happen. It is also useful in
--   parallel programs, to ensure pending work does not migrate to the
--   wrong thread.
--   
--   The primary use of this package is via the <a>deepseq</a> function, a
--   "deep" version of <a>seq</a>. It is implemented on top of an
--   <a>NFData</a> typeclass ("Normal Form Data", data structures with no
--   unevaluated components) which defines strategies for fully evaluating
--   different data types.
@package deepseq
@version 1.3.0.0


-- | This module provides an overloaded function, <a>deepseq</a>, 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:
--   
--   <pre>
--   import System.IO
--   import Control.DeepSeq
--   
--   main = do
--       h &lt;- openFile "f" ReadMode
--       s &lt;- hGetContents h
--       s `deepseq` hClose h
--       return s
--   </pre>
--   
--   <a>deepseq</a> differs from <a>seq</a> as it traverses data structures
--   deeply, for example, <a>seq</a> will evaluate only to the first
--   constructor in the list:
--   
--   <pre>
--   &gt; [1,2,undefined] `seq` 3
--   3
--   </pre>
--   
--   While <a>deepseq</a> will force evaluation of all the list elements:
--   
--   <pre>
--   &gt; [1,2,undefined] `deepseq` 3
--   *** Exception: Prelude.undefined
--   </pre>
--   
--   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).
module Control.DeepSeq

-- | <a>deepseq</a>: fully evaluates the first argument, before returning
--   the second.
--   
--   The name <a>deepseq</a> is used to illustrate the relationship to
--   <a>seq</a>: where <a>seq</a> is shallow in the sense that it only
--   evaluates the top level of its argument, <a>deepseq</a> traverses the
--   entire data structure evaluating it completely.
--   
--   <a>deepseq</a> 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
--   <tt>parallel</tt> 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
--   <tt>pseq</tt> from <a>Control.Parallel</a> in the <tt>parallel</tt>
--   package.
deepseq :: NFData a => a -> b -> b

-- | the deep analogue of <a>$!</a>. In the expression <tt>f $!! x</tt>,
--   <tt>x</tt> is fully evaluated before the function <tt>f</tt> is
--   applied to it.
($!!) :: NFData a => (a -> b) -> a -> b

-- | a variant of <a>deepseq</a> that is useful in some circumstances:
--   
--   <pre>
--   force x = x `deepseq` x
--   </pre>
--   
--   <tt>force x</tt> fully evaluates <tt>x</tt>, and then returns it. Note
--   that <tt>force x</tt> only performs evaluation when the value of
--   <tt>force x</tt> itself is demanded, so essentially it turns shallow
--   evaluation into deep evaluation.
force :: NFData a => a -> a

-- | A class of types that can be fully evaluated.
class NFData a where rnf a = a `seq` ()
rnf :: NFData a => a -> ()
instance [safe] (NFData a1, NFData a2, NFData a3, NFData a4, NFData a5, NFData a6, NFData a7, NFData a8, NFData a9) => NFData (a1, a2, a3, a4, a5, a6, a7, a8, a9)
instance [safe] (NFData a1, NFData a2, NFData a3, NFData a4, NFData a5, NFData a6, NFData a7, NFData a8) => NFData (a1, a2, a3, a4, a5, a6, a7, a8)
instance [safe] (NFData a1, NFData a2, NFData a3, NFData a4, NFData a5, NFData a6, NFData a7) => NFData (a1, a2, a3, a4, a5, a6, a7)
instance [safe] (NFData a1, NFData a2, NFData a3, NFData a4, NFData a5, NFData a6) => NFData (a1, a2, a3, a4, a5, a6)
instance [safe] (NFData a1, NFData a2, NFData a3, NFData a4, NFData a5) => NFData (a1, a2, a3, a4, a5)
instance [safe] (NFData a, NFData b, NFData c, NFData d) => NFData (a, b, c, d)
instance [safe] (NFData a, NFData b, NFData c) => NFData (a, b, c)
instance [safe] (NFData a, NFData b) => NFData (a, b)
instance [safe] (Ix a, NFData a, NFData b) => NFData (Array a b)
instance [safe] NFData a => NFData [a]
instance [safe] NFData Version
instance [safe] (NFData a, NFData b) => NFData (Either a b)
instance [safe] NFData a => NFData (Maybe a)
instance [safe] (RealFloat a, NFData a) => NFData (Complex a)
instance [safe] (Integral a, NFData a) => NFData (Ratio a)
instance [safe] NFData (a -> b)
instance [safe] NFData (Fixed a)
instance [safe] NFData Word64
instance [safe] NFData Word32
instance [safe] NFData Word16
instance [safe] NFData Word8
instance [safe] NFData Int64
instance [safe] NFData Int32
instance [safe] NFData Int16
instance [safe] NFData Int8
instance [safe] NFData ()
instance [safe] NFData Bool
instance [safe] NFData Char
instance [safe] NFData Double
instance [safe] NFData Float
instance [safe] NFData Integer
instance [safe] NFData Word
instance [safe] NFData Int