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


-- | Combinators and extra features for Par monads
--   
--   The modules below provide additional data structures, and other added
--   capabilities layered on top of the <a>Par</a> monad.
@package monad-par-extras
@version 0.3.3


-- | This module provides a notion of (Splittable) State that is compatible
--   with any Par monad.
--   
--   This module provides instances that make StateT-transformed monads
--   into valid Par monads.
module Control.Monad.Par.State

-- | A type in <a>SplittableState</a> is meant to be added to a Par monad
--   using StateT. It works like any other state except at <tt>fork</tt>
--   points, where the runtime system splits the state using
--   <a>splitState</a>.
--   
--   Common examples for applications of <a>SplittableState</a> would
--   include (1) routing a splittable random number generator through a
--   parallel computation, and (2) keeping a tree-index that locates the
--   current computation within the binary tree of <tt>fork</tt>s. Also, it
--   is possible to simply duplicate the state at all fork points, enabling
--   "thread local" copies of the state.
--   
--   The limitation of this approach is that the splitting method is fixed,
--   and the same at all <tt>fork</tt> points.
class SplittableState a
splitState :: SplittableState a => a -> (a, a)
instance (Control.Monad.Par.State.SplittableState s, Control.Monad.Par.Class.ParFuture fut p) => Control.Monad.Par.Class.ParFuture fut (Control.Monad.Trans.State.Strict.StateT s p)
instance (Control.Monad.Par.State.SplittableState s, Control.Monad.Par.Class.ParIVar iv p) => Control.Monad.Par.Class.ParIVar iv (Control.Monad.Trans.State.Strict.StateT s p)
instance (Control.Monad.Par.State.SplittableState s, Control.Monad.Par.Class.ParFuture fut p) => Control.Monad.Par.Class.ParFuture fut (Control.Monad.Trans.State.Lazy.StateT s p)
instance (Control.Monad.Par.State.SplittableState s, Control.Monad.Par.Class.ParIVar iv p) => Control.Monad.Par.Class.ParIVar iv (Control.Monad.Trans.State.Lazy.StateT s p)


-- | This module defines another Par-related class to capture the random
--   number generation capability.
--   
--   The <a>rand</a> operation provides deterministic parallel random
--   number generation from within a Par monad.
--   
--   Most likely one will simply use the <a>ParRand</a> the instance
--   provided in this file, which is based on a state transformer carrying
--   the random generator.
module Control.Monad.Par.RNG

-- | A <a>ParRand</a> monad is a Par monad with support for random number
--   generation..
class ParRand p where randInt = rand
rand :: (ParRand p, Random a) => p a
randInt :: ParRand p => p Int
runParRand :: ParFuture fut p => (p a -> a) -> StateT StdGen p a -> IO a

-- | A convenience type for the most standard
type ParRandStd par a = StateT StdGen par a
instance System.Random.RandomGen g => Control.Monad.Par.State.SplittableState g
instance (Control.Monad.Par.Class.ParFuture fut p, System.Random.RandomGen g) => Control.Monad.Par.RNG.ParRand (Control.Monad.Trans.State.Strict.StateT g p)


-- | A collection of useful parallel combinators based on top of a
--   <tt>Par</tt> monad.
--   
--   In particular, this module provides higher order functions for
--   traversing data structures in parallel.
module Control.Monad.Par.Combinator

-- | Applies the given function to each element of a data structure in
--   parallel (fully evaluating the results), and returns a new data
--   structure containing the results.
--   
--   <pre>
--   parMap f xs = mapM (spawnP . f) xs &gt;&gt;= mapM get
--   </pre>
--   
--   <tt>parMap</tt> is commonly used for lists, where it has this
--   specialised type:
--   
--   <pre>
--   parMap :: NFData b =&gt; (a -&gt; b) -&gt; [a] -&gt; Par [b]
--   </pre>
parMap :: (Traversable t, NFData b, ParFuture iv p) => (a -> b) -> t a -> p (t b)

-- | Like <a>parMap</a>, but the function is a <tt>Par</tt> monad
--   operation.
--   
--   <pre>
--   parMapM f xs = mapM (spawn . f) xs &gt;&gt;= mapM get
--   </pre>
parMapM :: (Traversable t, NFData b, ParFuture iv p) => (a -> p b) -> t a -> p (t b)

-- | Computes a binary map/reduce over a finite range. The range is
--   recursively split into two, the result for each half is computed in
--   parallel, and then the two results are combined. When the range
--   reaches the threshold size, the remaining elements of the range are
--   computed sequentially.
--   
--   For example, the following is a parallel implementation of
--   
--   <pre>
--   foldl (+) 0 (map (^2) [1..10^6])
--   </pre>
--   
--   <pre>
--   parMapReduceRangeThresh 100 (InclusiveRange 1 (10^6))
--          (\x -&gt; return (x^2))
--          (\x y -&gt; return (x+y))
--          0
--   </pre>
parMapReduceRangeThresh :: (NFData a, ParFuture iv p) => Int -> InclusiveRange -> (Int -> p a) -> (a -> a -> p a) -> a -> p a

-- | "Auto-partitioning" version of <a>parMapReduceRangeThresh</a> that
--   chooses the threshold based on the size of the range and the number of
--   processors..
parMapReduceRange :: (NFData a, ParFuture iv p) => InclusiveRange -> (Int -> p a) -> (a -> a -> p a) -> a -> p a
data InclusiveRange
InclusiveRange :: Int -> Int -> InclusiveRange

-- | Parallel for-loop over an inclusive range. Semantically equivalent to
--   
--   <pre>
--   parFor (InclusiveRange n m) f = forM_ [n..m] f
--   </pre>
--   
--   except that the implementation will split the work into an unspecified
--   number of subtasks in an attempt to gain parallelism. The exact number
--   of subtasks is chosen at runtime, and is probably a small multiple of
--   the available number of processors.
--   
--   Strictly speaking the semantics of <a>parFor</a> depends on the number
--   of processors, and its behaviour is therefore not deterministic.
--   However, a good rule of thumb is to not have any interdependencies
--   between the elements; if this rule is followed then <tt>parFor</tt>
--   has deterministic semantics. One easy way to follow this rule is to
--   only use <a>put</a> or <a>put_</a> in <tt>f</tt>, never <a>get</a>.
parFor :: (ParFuture iv p) => InclusiveRange -> (Int -> p ()) -> p ()


-- | This module defines the <a>AList</a> type, a list that supports
--   constant-time append, and is therefore ideal for building the result
--   of tree-shaped parallel computations.

-- | <i>Deprecated: This structure does not perform well, and will be
--   removed in future versions</i>
module Control.Monad.Par.AList

-- | List that support constant-time append (sometimes called join-lists).
data AList a
ANil :: AList a
ASing :: a -> AList a
Append :: (AList a) -> (AList a) -> AList a
AList :: [a] -> AList a

-- | <i>O(1)</i> an empty <a>AList</a>
empty :: AList a

-- | <i>O(1)</i> a singleton <a>AList</a>
singleton :: a -> AList a

-- | <i>O(1)</i> prepend an element
cons :: a -> AList a -> AList a

-- | <i>O(n)</i> take the head element of an <a>AList</a>
--   
--   NB. linear-time, because the list might look like this:
--   
--   <pre>
--   (((... `append` a) `append` b) `append` c)
--   </pre>
head :: AList a -> a

-- | <i>O(n)</i> take the tail element of an <a>AList</a>
tail :: AList a -> AList a

-- | <i>O(n)</i> find the length of an <a>AList</a>
length :: AList a -> Int

-- | <i>O(n)</i> returns <a>True</a> if the <a>AList</a> is empty
null :: AList a -> Bool

-- | <i>O(1)</i> Append two <a>AList</a>s
append :: AList a -> AList a -> AList a

-- | <i>O(n)</i> converts an <a>AList</a> to an ordinary list
toList :: AList a -> [a]

-- | <i>O(1)</i> convert an ordinary list to an <a>AList</a>
fromList :: [a] -> AList a

-- | Convert an ordinary list, but do so using <a>Append</a> and
--   <a>ASing</a> rather than <a>AList</a>
fromListBalanced :: [a] -> AList a
filter :: (a -> Bool) -> AList a -> AList a

-- | The usual <a>map</a> operation.
map :: (a -> b) -> AList a -> AList b
partition :: (a -> Bool) -> AList a -> (AList a, AList a)

-- | A parMap over an AList can result in more balanced parallelism than
--   the default parMap over Traversable data types. parMap :: NFData b
--   =&gt; (a -&gt; b) -&gt; AList a -&gt; Par (AList b)
--   
--   Build a balanced <a>AList</a> in parallel, constructing each element
--   as a function of its index. The threshold argument provides control
--   over the degree of parallelism. It indicates under what number of
--   elements the build process should switch from parallel to serial.
parBuildThresh :: (NFData a, ParFuture f p) => Int -> InclusiveRange -> (Int -> a) -> p (AList a)

-- | Variant of <a>parBuildThresh</a> in which the element-construction
--   function is itself a <tt>Par</tt> computation.
parBuildThreshM :: (NFData a, ParFuture f p) => Int -> InclusiveRange -> (Int -> p a) -> p (AList a)

-- | "Auto-partitioning" version of <a>parBuildThresh</a> that chooses the
--   threshold based on the size of the range and the number of
--   processors..
parBuild :: (NFData a, ParFuture f p) => InclusiveRange -> (Int -> a) -> p (AList a)

-- | like <a>parBuild</a>, but the construction function is monadic
parBuildM :: (NFData a, ParFuture f p) => InclusiveRange -> (Int -> p a) -> p (AList a)
depth :: AList a -> Int

-- | Balance the tree representation of an AList.
balance :: AList a -> AList a
instance Control.DeepSeq.NFData a => Control.DeepSeq.NFData (Control.Monad.Par.AList.AList a)
instance GHC.Show.Show a => GHC.Show.Show (Control.Monad.Par.AList.AList a)
instance Data.Serialize.Serialize a => Data.Serialize.Serialize (Control.Monad.Par.AList.AList a)
instance GHC.Classes.Eq a => GHC.Classes.Eq (Control.Monad.Par.AList.AList a)
