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


-- | Specify that lifted values were forced to WHNF or NF.
--   
--   Alternative to bang patterns using CBV functions and unlifted data
--   types. Tag your values to maintain the invariant that they were
--   forced. Avoid liveness leaks on long lived data structures.
--   
--   Main tutorial on the only module. Here is a taste of how it will look
--   like.
--   
--   <pre>
--   import Data.Map.Lazy as ML -- Spine strict
--   
--   -- No references on added leafs even though it is a lazy map.
--   basicEvent :: ML.Map Char (ForcedWHNF Int) -&gt; IO (ML.Map Char (ForcedWHNF Int))
--   basicEvent map0 = do
--     let
--       -- Step1: bind the strict value with a strict let. (2 + 2) reduced
--       -- before val0 is bound.
--       val0 :: StrictValueExtractor (ForcedWHNF Int)
--       val0 = strictlyWHNF (2 + 2)
--       -- val0 = strictlyWHNF (error "argument evaluated") -- would fail
--   
--       -- Step2: extract the strict value to be use on lazy setting. A
--       -- neccesary idiom to avoid a pitfall.
--       val1 = case val0 of { Pairy val0' ext -&gt; ext val0' }
--   
--       -- Step3: Store the value free of references. Even though map1 is a lazy
--       -- map, the references to evaluate val1 were already freed.
--       map1 = ML.insert 'a' val1 map0
--     pure map1
--   </pre>
@package data-forced
@version 0.2.0.0

module Data.Forced

-- | Unlifted pair type. When a value of this type is bound, it will have
--   already evaluated <tt>u</tt>.
data Pairy (u :: UnliftedType) (l :: LiftedType) :: UnliftedType
[Pairy] :: u -> l -> Pairy u l

-- | A type synonym for the unlifted pair type synonym. It contains a
--   strict value and a way to extract it to a lazy/normal context.
type StrictValueExtractor a = Pairy (Strict a) (Strict a -> a)

-- | A wrapper for a lifted type that makes sure to have it evaluated.
data Strict (a :: LiftedType) :: UnliftedType

-- | Contains a value of type <tt>a</tt> that has been forced to
--   <b>W</b>eak <b>H</b>ead <b>N</b>ormal <b>F</b>orm. Constructor not
--   exported (so no <a>coerce</a>).
data ForcedWHNF a

-- | The only way to extract the underlying value.
pattern ForcedWHNF :: forall a. a -> ForcedWHNF a

-- | Contains a value of type <tt>a</tt> that has been forced to
--   <b>N</b>ormal <b>F</b>orm. Constructor not exported (so no
--   <a>coerce</a>).
data ForcedNF a

-- | The only way to extract the underlying value.
pattern ForcedNF :: forall a. a -> ForcedNF a

-- | This is a CBV function. Evaluates the argument to WHNF before
--   returning.
strictlyWHNF :: forall a. a -> StrictValueExtractor (ForcedWHNF a)

-- | This is a CBV function. Evaluates the argument to NF before returning.
strictlyNF :: forall a. NFData a => a -> StrictValueExtractor (ForcedNF a)