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


-- | GHC.Generics-based Control.DeepSeq.rnf implementation
--   
--   This package provides a <a>GHC.Generics</a>-based
--   <a>Control.DeepSeq.Generics.genericRnf</a> function which can be used
--   for providing a <a>rnf</a> implementation. See the documentation for
--   the <a>genericRnf</a> function in the <a>Control.DeepSeq.Generics</a>
--   module to get started.
--   
--   The original idea was pioneered in the <tt>generic-deepseq</tt>
--   package (see
--   <a>http://www.haskell.org/pipermail/haskell-cafe/2012-February/099551.html</a>
--   for more information).
--   
--   This package differs from the <tt>generic-deepseq</tt> package by
--   working in combination with the existing <tt>deepseq</tt> package as
--   opposed to defining a conflicting drop-in replacement for
--   <tt>deepseq</tt>'s <tt>Control.Deepseq</tt> module.
@package deepseq-generics
@version 0.1.1.0


-- | Note: Beyond the primary scope of providing the <a>genericRnf</a>
--   helper, this module also re-exports the definitions from
--   <a>Control.DeepSeq</a> for convenience. If this poses any problems,
--   just use qualified or explicit import statements (see code usage
--   example in the <a>genericRnf</a> description)
module Control.DeepSeq.Generics

-- | <a>GHC.Generics</a>-based <a>rnf</a> implementation
--   
--   This provides a generic <a>rnf</a> implementation for one type at a
--   time. If the type of the value <a>genericRnf</a> is asked to reduce to
--   NF contains values of other types, those types have to provide
--   <a>NFData</a> instances. This also means that recursive types can only
--   be used with <a>genericRnf</a> if a <a>NFData</a> instance has been
--   defined as well (see examples below).
--   
--   The typical usage for <a>genericRnf</a> is for reducing boilerplate
--   code when defining <a>NFData</a> instances for ordinary algebraic
--   datatypes. See the code below for some simple usage examples:
--   
--   <pre>
--   {-# LANGUAGE DeriveGeneric #-}
--   
--   import Control.DeepSeq
--   import Control.DeepSeq.Generics (genericRnf)
--   import GHC.Generics
--   
--   -- simple record
--   data Foo = Foo AccountId Name Address
--            deriving Generic
--   
--   type Address      = [String]
--   type Name         = String
--   newtype AccountId = AccountId Int
--   
--   instance NFData AccountId
--   instance NFData Foo where rnf = genericRnf
--   
--   -- recursive list-like type
--   data N = Z | S N deriving Generic
--   
--   instance NFData N where rnf = genericRnf
--   
--   -- parametric &amp; recursive type
--   data Bar a = Bar0 | Bar1 a | Bar2 (Bar a)
--              deriving Generic
--   
--   instance NFData a =&gt; NFData (Bar a) where rnf = genericRnf
--   </pre>
--   
--   Note: The <a>GNFData</a> type-class showing up in the type-signature
--   is used internally and not exported on purpose currently.
genericRnf :: (Generic a, GNFData (Rep a)) => a -> ()

-- | Variant of <a>genericRnf</a> which supports derivation for uninhabited
--   types.
--   
--   For instance, the type
--   
--   <pre>
--   data TagFoo deriving Generic
--   </pre>
--   
--   would cause a compile-time error with <a>genericRnf</a>, but with
--   <a>genericRnfV1</a> the error is deferred to run-time:
--   
--   <pre>
--   Prelude&gt; genericRnf (undefined :: TagFoo)
--   
--   &lt;interactive&gt;:1:1:
--       No instance for (GNFData V1) arising from a use of `genericRnf'
--       Possible fix: add an instance declaration for (GNFData V1)
--       In the expression: genericRnf (undefined :: TagFoo)
--       In an equation for `it': it = genericRnf (undefined :: TagFoo)
--   
--   Prelude&gt; genericRnfV1 (undefined :: TagFoo)
--   *** Exception: Control.DeepSeq.Generics.genericRnfV1: NF not defined for uninhabited types
--   </pre>
--   
--   <i>Since: 0.1.1.0</i>
genericRnfV1 :: (Generic a, GNFDataV1 (Rep a)) => a -> ()

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

-- | 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
rnf :: NFData a => a -> ()

-- | 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
instance (GNFDataV1 a, GNFDataV1 b) => GNFDataV1 (a :+: b)
instance (GNFDataV1 a, GNFDataV1 b) => GNFDataV1 (a :*: b)
instance GNFDataV1 a => GNFDataV1 (M1 i c a)
instance NFData a => GNFDataV1 (K1 i a)
instance GNFDataV1 U1
instance GNFDataV1 V1
instance (GNFData a, GNFData b) => GNFData (a :+: b)
instance (GNFData a, GNFData b) => GNFData (a :*: b)
instance GNFData a => GNFData (M1 i c a)
instance NFData a => GNFData (K1 i a)
instance GNFData U1