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


-- | A framework for safe, programmable, speculative parallelism
--   
--   A framework for safe, programmable, speculative parallelism, loosely
--   based on
--   <a>http://research.microsoft.com/pubs/118795/pldi026-vaswani.pdf</a>
--   
--   <tt><a>spec</a> g f a</tt> evaluates <tt>f g</tt> while forcing
--   <tt>a</tt>, if <tt>g == a</tt> then <tt>f g</tt> is returned.
--   Otherwise <tt>f a</tt> is evaluated.
--   
--   Furthermore, if the argument has already been evaluated, we avoid
--   sparking the parallel computation at all.
--   
--   If a good guess at the value of <tt>a</tt> is available, this is one
--   way to induce parallelism in an otherwise sequential task.
--   
--   However, if the guess isn't available more cheaply than the actual
--   answer, then this saves no work and if the guess is wrong, you risk
--   evaluating the function twice.
--   
--   <pre>
--   spec a f a = a `seq` f a
--   </pre>
--   
--   The best-case timeline looks like:
--   
--   <pre>
--   [---- f g ----]
--      [----- a -----]
--   [-- spec g f a --]
--   </pre>
--   
--   The worst-case timeline looks like:
--   
--   <pre>
--   [---- f g ----]
--      [----- a -----]
--                    [---- f a ----]
--   [------- spec g f a -----------]
--   </pre>
--   
--   Compared to the unspeculated timeline of
--   
--   <pre>
--   [---- a -----]
--                [---- f a ----]
--   </pre>
--   
--   Changes since 0.0.1
--   
--   <ul>
--   <li><a>specFoldr1</a> bug fix</li>
--   <li>Added <a>spec'</a> combinator</li>
--   </ul>
--   
--   Changes since 0.0.0
--   
--   <ul>
--   <li>Added <a>WithoutSpeculation</a> and <a>WrappedFoldable</a></li>
--   </ul>
@package speculation
@version 0.0.2

module Control.Concurrent.Speculation

-- | <tt><a>spec</a> g f a</tt> evaluates <tt>f g</tt> while forcing
--   <tt>a</tt>, if <tt>g == a</tt> then <tt>f g</tt> is returned.
--   Otherwise <tt>f a</tt> is evaluated.
--   
--   Furthermore, if the argument has already been evaluated, we avoid
--   sparking the parallel computation at all.
--   
--   If a good guess at the value of <tt>a</tt> is available, this is one
--   way to induce parallelism in an otherwise sequential task.
--   
--   However, if the guess isn't available more cheaply than the actual
--   answer, then this saves no work and if the guess is wrong, you risk
--   evaluating the function twice.
--   
--   <pre>
--   spec a f a = a `seq` f a
--   </pre>
--   
--   The best-case timeline looks like:
--   
--   <pre>
--   [---- f g ----]
--      [----- a -----]
--   [-- spec g f a --]
--   </pre>
--   
--   The worst-case timeline looks like:
--   
--   <pre>
--   [---- f g ----]
--      [----- a -----]
--                    [---- f a ----]
--   [------- spec g f a -----------]
--   </pre>
--   
--   Compared to the unspeculated timeline of
--   
--   <pre>
--   [---- a -----]
--                [---- f a ----]
--   </pre>
spec :: (Eq a) => a -> (a -> b) -> a -> b

-- | <tt><a>spec'</a> g f a</tt> evaluates a function <tt>f </tt> using a
--   cheap guess <tt>g</tt> at the argument in parallel with forcing the
--   argument.
--   
--   This is one way to induce parallelism in an otherwise sequential task.
--   Unlike <a>spec</a> this version does not check to see if the argument
--   has already been evaluated before evaluating the speculated version.
--   This is useful when you know <a>evaluated</a> will always return
--   False.
--   
--   The following identity holds:
--   
--   <pre>
--   spec' a f a = a `seq` f a
--   </pre>
spec' :: (Eq a) => a -> (a -> b) -> a -> b

-- | Returns a guess as to whether or not a value has been evaluated. This
--   is an impure function that relies on GHC internals and will return
--   false negatives, but (hopefully) no false positives.
evaluated :: a -> Bool

-- | Compute a right biased fold. The estimator function provides a guess
--   at the value of the suffix
specFoldr :: (Speculative f, Eq b) => (Int -> b) -> (a -> b -> b) -> b -> f a -> b

-- | Compute a left-biased fold. The estimator function provides a guess at
--   the value of the prefix
specFoldl :: (Speculative f, Eq b) => (Int -> b) -> (b -> a -> b) -> b -> f a -> b
class (Foldable f) => Speculative f
specFoldr1 :: (Speculative f, Eq a) => (Int -> a) -> (a -> a -> a) -> f a -> a
specFoldrN :: (Speculative f, Eq b) => Int -> (Int -> b) -> (a -> b -> b) -> b -> f a -> b
specFoldl1 :: (Speculative f, Eq a) => (Int -> a) -> (a -> a -> a) -> f a -> a
specFoldlN :: (Speculative f, Eq b) => Int -> (Int -> b) -> (b -> a -> b) -> b -> f a -> b
newtype WrappedFoldable f a
WrappedFoldable :: f a -> WrappedFoldable f a
getWrappedFoldable :: WrappedFoldable f a -> f a
newtype WithoutSpeculation f a
WithoutSpeculation :: f a -> WithoutSpeculation f a
getWithoutSpeculation :: WithoutSpeculation f a -> f a
instance (Functor f) => Functor (WithoutSpeculation f)
instance (Foldable f) => Foldable (WithoutSpeculation f)
instance (Traversable f) => Traversable (WithoutSpeculation f)
instance (Functor f) => Functor (WrappedFoldable f)
instance (Foldable f) => Foldable (WrappedFoldable f)
instance (Traversable f) => Traversable (WrappedFoldable f)
instance (Typeable1 f, Data (f a), Data a) => Data (WithoutSpeculation f a)
instance (Foldable f) => Speculative (WithoutSpeculation f)
instance (Typeable1 f) => Typeable1 (WithoutSpeculation f)
instance (Typeable1 f, Data (f a), Data a) => Data (WrappedFoldable f a)
instance (Typeable1 f) => Typeable1 (WrappedFoldable f)
instance (Foldable f) => Speculative (WrappedFoldable f)
instance Speculative Seq
instance Speculative IntMap
instance Speculative (Map a)
instance Speculative Set
instance (Ix i) => Speculative (Array i)
instance Speculative Maybe
instance Speculative []