-- 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.4.1.2


-- | 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).
--   
--   <i>Since: 1.1.0.0</i>
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.
--   
--   <i>Since: 1.1.0.0</i>
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.
--   
--   <i>Since: 1.2.0.0</i>
($!!) :: (NFData a) => (a -> b) -> a -> b
infixr 0 $!!

-- | 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.
--   
--   <a>force</a> can be conveniently used in combination with
--   <tt>ViewPatterns</tt>:
--   
--   <pre>
--   {-# LANGUAGE BangPatterns, ViewPatterns #-}
--   import Control.DeepSeq
--   
--   someFun :: ComplexData -&gt; SomeResult
--   someFun (force -&gt; !arg) = {- 'arg' will be fully evaluated -}
--   </pre>
--   
--   Another useful application is to combine <a>force</a> with
--   <a>evaluate</a> in order to force deep evaluation relative to other
--   <a>IO</a> operations:
--   
--   <pre>
--   import Control.Exception (evaluate)
--   import Control.DeepSeq
--   
--   main = do
--     result &lt;- evaluate $ force $ pureComputation
--     {- 'result' will be fully evaluated at this point -}
--     return ()
--   </pre>
--   
--   <i>Since: 1.2.0.0</i>
force :: (NFData a) => a -> a

-- | A class of types that can be fully evaluated.
--   
--   <i>Since: 1.1.0.0</i>
class NFData a

-- | <a>rnf</a> should reduce its argument to normal form (that is, fully
--   evaluate all sub-components), and then return '()'.
--   
--   <h3><a>Generic</a> <a>NFData</a> deriving</h3>
--   
--   Starting with GHC 7.2, you can automatically derive instances for
--   types possessing a <a>Generic</a> instance.
--   
--   <pre>
--   {-# LANGUAGE DeriveGeneric #-}
--   
--   import GHC.Generics (Generic)
--   import Control.DeepSeq
--   
--   data Foo a = Foo a String
--                deriving (Eq, Generic)
--   
--   instance NFData a =&gt; NFData (Foo a)
--   
--   data Colour = Red | Green | Blue
--                 deriving Generic
--   
--   instance NFData Colour
--   </pre>
--   
--   Starting with GHC 7.10, the example above can be written more
--   concisely by enabling the new <tt>DeriveAnyClass</tt> extension:
--   
--   <pre>
--   {-# LANGUAGE DeriveGeneric, DeriveAnyClass #-}
--   
--   import GHC.Generics (Generic)
--   import Control.DeepSeq
--   
--   data Foo a = Foo a String
--                deriving (Eq, Generic, NFData)
--   
--   data Colour = Red | Green | Blue
--                 deriving (Generic, NFData)
--   </pre>
--   
--   <h3>Compatibility with previous <tt>deepseq</tt> versions</h3>
--   
--   Prior to version 1.4.0.0, the default implementation of the <a>rnf</a>
--   method was defined as
--   
--   <pre>
--   <a>rnf</a> a = <a>seq</a> a ()
--   </pre>
--   
--   However, starting with <tt>deepseq-1.4.0.0</tt>, the default
--   implementation is based on <tt>DefaultSignatures</tt> allowing for
--   more accurate auto-derived <a>NFData</a> instances. If you need the
--   previously used exact default <a>rnf</a> method implementation
--   semantics, use
--   
--   <pre>
--   instance NFData Colour where rnf x = seq x ()
--   </pre>
--   
--   or alternatively
--   
--   <pre>
--   {-# LANGUAGE BangPatterns #-}
--   instance NFData Colour where rnf !_ = ()
--   </pre>
rnf :: NFData a => a -> ()
instance Control.DeepSeq.GNFData GHC.Generics.V1
instance Control.DeepSeq.GNFData GHC.Generics.U1
instance Control.DeepSeq.NFData a => Control.DeepSeq.GNFData (GHC.Generics.K1 i a)
instance Control.DeepSeq.GNFData a => Control.DeepSeq.GNFData (GHC.Generics.M1 i c a)
instance (Control.DeepSeq.GNFData a, Control.DeepSeq.GNFData b) => Control.DeepSeq.GNFData (a GHC.Generics.:*: b)
instance (Control.DeepSeq.GNFData a, Control.DeepSeq.GNFData b) => Control.DeepSeq.GNFData (a GHC.Generics.:+: b)
instance Control.DeepSeq.NFData GHC.Types.Int
instance Control.DeepSeq.NFData GHC.Types.Word
instance Control.DeepSeq.NFData GHC.Integer.Type.Integer
instance Control.DeepSeq.NFData GHC.Types.Float
instance Control.DeepSeq.NFData GHC.Types.Double
instance Control.DeepSeq.NFData GHC.Types.Char
instance Control.DeepSeq.NFData GHC.Types.Bool
instance Control.DeepSeq.NFData ()
instance Control.DeepSeq.NFData GHC.Int.Int8
instance Control.DeepSeq.NFData GHC.Int.Int16
instance Control.DeepSeq.NFData GHC.Int.Int32
instance Control.DeepSeq.NFData GHC.Int.Int64
instance Control.DeepSeq.NFData GHC.Word.Word8
instance Control.DeepSeq.NFData GHC.Word.Word16
instance Control.DeepSeq.NFData GHC.Word.Word32
instance Control.DeepSeq.NFData GHC.Word.Word64
instance Control.DeepSeq.NFData (Data.Proxy.Proxy a)
instance Control.DeepSeq.NFData a => Control.DeepSeq.NFData (Data.Functor.Identity.Identity a)
instance Control.DeepSeq.NFData Data.Void.Void
instance Control.DeepSeq.NFData GHC.Natural.Natural
instance Control.DeepSeq.NFData (Data.Fixed.Fixed a)
instance Control.DeepSeq.NFData (a -> b)
instance (GHC.Real.Integral a, Control.DeepSeq.NFData a) => Control.DeepSeq.NFData (GHC.Real.Ratio a)
instance Control.DeepSeq.NFData a => Control.DeepSeq.NFData (Data.Complex.Complex a)
instance Control.DeepSeq.NFData a => Control.DeepSeq.NFData (GHC.Base.Maybe a)
instance (Control.DeepSeq.NFData a, Control.DeepSeq.NFData b) => Control.DeepSeq.NFData (Data.Either.Either a b)
instance Control.DeepSeq.NFData Data.Version.Version
instance Control.DeepSeq.NFData a => Control.DeepSeq.NFData [a]
instance Control.DeepSeq.NFData a => Control.DeepSeq.NFData (Control.Applicative.ZipList a)
instance Control.DeepSeq.NFData a => Control.DeepSeq.NFData (Control.Applicative.Const a b)
instance (GHC.Arr.Ix a, Control.DeepSeq.NFData a, Control.DeepSeq.NFData b) => Control.DeepSeq.NFData (GHC.Arr.Array a b)
instance Control.DeepSeq.NFData a => Control.DeepSeq.NFData (Data.Ord.Down a)
instance Control.DeepSeq.NFData a => Control.DeepSeq.NFData (Data.Monoid.Dual a)
instance Control.DeepSeq.NFData a => Control.DeepSeq.NFData (Data.Monoid.First a)
instance Control.DeepSeq.NFData a => Control.DeepSeq.NFData (Data.Monoid.Last a)
instance Control.DeepSeq.NFData Data.Monoid.Any
instance Control.DeepSeq.NFData Data.Monoid.All
instance Control.DeepSeq.NFData a => Control.DeepSeq.NFData (Data.Monoid.Sum a)
instance Control.DeepSeq.NFData a => Control.DeepSeq.NFData (Data.Monoid.Product a)
instance Control.DeepSeq.NFData (System.Mem.StableName.StableName a)
instance Control.DeepSeq.NFData GHC.Conc.Sync.ThreadId
instance Control.DeepSeq.NFData Data.Unique.Unique
instance Control.DeepSeq.NFData Data.Typeable.Internal.TypeRep
instance Control.DeepSeq.NFData Data.Typeable.Internal.TyCon
instance Control.DeepSeq.NFData GHC.Fingerprint.Type.Fingerprint
instance Control.DeepSeq.NFData Foreign.C.Types.CChar
instance Control.DeepSeq.NFData Foreign.C.Types.CSChar
instance Control.DeepSeq.NFData Foreign.C.Types.CUChar
instance Control.DeepSeq.NFData Foreign.C.Types.CShort
instance Control.DeepSeq.NFData Foreign.C.Types.CUShort
instance Control.DeepSeq.NFData Foreign.C.Types.CInt
instance Control.DeepSeq.NFData Foreign.C.Types.CUInt
instance Control.DeepSeq.NFData Foreign.C.Types.CLong
instance Control.DeepSeq.NFData Foreign.C.Types.CULong
instance Control.DeepSeq.NFData Foreign.C.Types.CPtrdiff
instance Control.DeepSeq.NFData Foreign.C.Types.CSize
instance Control.DeepSeq.NFData Foreign.C.Types.CWchar
instance Control.DeepSeq.NFData Foreign.C.Types.CSigAtomic
instance Control.DeepSeq.NFData Foreign.C.Types.CLLong
instance Control.DeepSeq.NFData Foreign.C.Types.CULLong
instance Control.DeepSeq.NFData Foreign.C.Types.CIntPtr
instance Control.DeepSeq.NFData Foreign.C.Types.CUIntPtr
instance Control.DeepSeq.NFData Foreign.C.Types.CIntMax
instance Control.DeepSeq.NFData Foreign.C.Types.CUIntMax
instance Control.DeepSeq.NFData Foreign.C.Types.CClock
instance Control.DeepSeq.NFData Foreign.C.Types.CTime
instance Control.DeepSeq.NFData Foreign.C.Types.CUSeconds
instance Control.DeepSeq.NFData Foreign.C.Types.CSUSeconds
instance Control.DeepSeq.NFData Foreign.C.Types.CFloat
instance Control.DeepSeq.NFData Foreign.C.Types.CDouble
instance Control.DeepSeq.NFData Foreign.C.Types.CFile
instance Control.DeepSeq.NFData Foreign.C.Types.CFpos
instance Control.DeepSeq.NFData Foreign.C.Types.CJmpBuf
instance (Control.DeepSeq.NFData a, Control.DeepSeq.NFData b) => Control.DeepSeq.NFData (a, b)
instance (Control.DeepSeq.NFData a, Control.DeepSeq.NFData b, Control.DeepSeq.NFData c) => Control.DeepSeq.NFData (a, b, c)
instance (Control.DeepSeq.NFData a, Control.DeepSeq.NFData b, Control.DeepSeq.NFData c, Control.DeepSeq.NFData d) => Control.DeepSeq.NFData (a, b, c, d)
instance (Control.DeepSeq.NFData a1, Control.DeepSeq.NFData a2, Control.DeepSeq.NFData a3, Control.DeepSeq.NFData a4, Control.DeepSeq.NFData a5) => Control.DeepSeq.NFData (a1, a2, a3, a4, a5)
instance (Control.DeepSeq.NFData a1, Control.DeepSeq.NFData a2, Control.DeepSeq.NFData a3, Control.DeepSeq.NFData a4, Control.DeepSeq.NFData a5, Control.DeepSeq.NFData a6) => Control.DeepSeq.NFData (a1, a2, a3, a4, a5, a6)
instance (Control.DeepSeq.NFData a1, Control.DeepSeq.NFData a2, Control.DeepSeq.NFData a3, Control.DeepSeq.NFData a4, Control.DeepSeq.NFData a5, Control.DeepSeq.NFData a6, Control.DeepSeq.NFData a7) => Control.DeepSeq.NFData (a1, a2, a3, a4, a5, a6, a7)
instance (Control.DeepSeq.NFData a1, Control.DeepSeq.NFData a2, Control.DeepSeq.NFData a3, Control.DeepSeq.NFData a4, Control.DeepSeq.NFData a5, Control.DeepSeq.NFData a6, Control.DeepSeq.NFData a7, Control.DeepSeq.NFData a8) => Control.DeepSeq.NFData (a1, a2, a3, a4, a5, a6, a7, a8)
instance (Control.DeepSeq.NFData a1, Control.DeepSeq.NFData a2, Control.DeepSeq.NFData a3, Control.DeepSeq.NFData a4, Control.DeepSeq.NFData a5, Control.DeepSeq.NFData a6, Control.DeepSeq.NFData a7, Control.DeepSeq.NFData a8, Control.DeepSeq.NFData a9) => Control.DeepSeq.NFData (a1, a2, a3, a4, a5, a6, a7, a8, a9)