-- 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.
--   
--   Note: The ability to auto-derive via <a>GHC.Generics</a> has been
--   merged into <tt>deepseq-1.4.0.0</tt>. This package is now still useful
--   for writing code that's also compatible with older <tt>deepseq</tt>
--   versions not yet providing <a>GHC.Generics</a>-support.
@package deepseq-generics
@version 0.1.1.2


-- | 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)
--   
--   <b>NOTE</b>: Starting with <tt>deepseq-1.4.0.0</tt>, <a>NFData</a>
--   gained support for generic derivation via <tt>DefaultSignatures</tt>.
--   The new default <a>rnf</a> method implementation is then equivalent to
--   
--   <pre>
--   instance NFData MyType where
--     <a>rnf</a> = <a>genericRnfV1</a>
--   </pre>
--   
--   See documentation of <a>rnf</a> for more details on how to use the new
--   built-in <a>Generic</a> support.
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>
--   
--   <b>NOTE</b>: 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.
--   
--   <i>Since: 1.1.0.0</i>
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.
--   
--   <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 -> ()

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