Merge branch 'master' of github.com:simonmar/monad-par

abstract-par/Control/Monad/Par/Class.hs

@@ -4,21 +4,22 @@
 -- UndecidableInstances
 
 {-|
-
     This module establishes a class hierarchy that captures the
-    interface(s) for valid Par monads.  In particular, the functionality
-    is split into layers: e.g. Futures vs. full IVars vs. Chans (Streams).  
-    
-    Not all Par monad schedulers must provide all functionality.
+    interfaces of @Par@ monads.  There are two layers: simple futures
+    ('ParFuture') and full @IVars@ ('ParIVar').  All @Par@ monads are
+    expected to implement the former, some also implement the latter.
 
     For more documentation of the programming model, see  
 
-      * The "Control.Monad.Par" module in the @monad-par@ package.
-      * The wiki/tutorial (<http://www.haskell.org/haskellwiki/Par_Monad:_A_Parallelism_Tutorial>)
-      * The original paper (<http://www.cs.indiana.edu/~rrnewton/papers/haskell2011_monad-par.pdf>)
-      * Tutorial slides (<http://community.haskell.org/~simonmar/slides/CUFP.pdf>)
-      * Other slides: <http://www.cs.ox.ac.uk/ralf.hinze/WG2.8/28/slides/simon.pdf>, 
-                      <http://www.cs.indiana.edu/~rrnewton/talks/2011_HaskellSymposium_ParMonad.pdf>
+    * The "Control.Monad.Par" module in the @monad-par@ package.
+
+    * The wiki\/tutorial (<http://www.haskell.org/haskellwiki/Par_Monad:_A_Parallelism_Tutorial>)
+
+    * The original paper (<http://www.cs.indiana.edu/~rrnewton/papers/haskell2011_monad-par.pdf>)
+
+    * Tutorial slides (<http://community.haskell.org/~simonmar/slides/CUFP.pdf>)
+
+    * Other slides (<http://www.cs.ox.ac.uk/ralf.hinze/WG2.8/28/slides/simon.pdf>, <http://www.cs.indiana.edu/~rrnewton/talks/2011_HaskellSymposium_ParMonad.pdf>)
 
  -}
 --  
@@ -63,6 +64,8 @@ class Monad m => ParFuture future m | m -> future where
 
   -- | Like 'spawn', but the result is only head-strict, not fully-strict.
   spawn_ :: m a -> m (future a)
+
+  -- | Wait for the result of a future, and then return it.
   get    :: future a -> m a
 
   -- | Spawn a pure (rather than monadic) computation.  Fully-strict.

abstract-par/abstract-par.cabal

@@ -8,26 +8,15 @@ Synopsis:            Type classes generalizing the functionality of the 'monad-p
 --  0.3      : Factored out of monad-par package.
 --  0.3.1    : Relax deepseq restriction
 
-
-Description:         The 'Par' monad(s) offer an alternative 
-                     parallel programming API to that provided by the 
-                     @parallel@ package.
-
-                     A 'Par' monad allows the simple description of
-                     parallel computations, and can be used to add
-                     parallelism to pure Haskell code.  The basic API
-                     is straightforward: a @Par@ monad supports forking
-                     and simple communication in terms of 'IVar's.
-
-                     This module is an interface module only. It
-                     provides a number of type clasess, but not an
-                     implementation.  The type classes separate different 
-                     levels of @Par@ functionality.  See the 
-                     "Control.Monad.Par.Class" module for more details.
-
-                     The 'monad-par' library is one example of a
-                     concrete library providing this interface.
-
+Description:
+  The 'Par' monad offers a parallel programming API based on dataflow
+  programming.  To use the `Par` monad, install the @monad-par@
+  package, which includes this package as a dependency.
+  .
+  This package is an abstract interface only. It provides a number of
+  type clasess, but not an implementation.  The type classes separate
+  different levels of @Par@ functionality.  See the
+  "Control.Monad.Par.Class" module for more details.
 
 Homepage:            https://github.com/simonmar/monad-par
 License:             BSD3
@@ -45,11 +34,11 @@ extra-source-files:
 
 Library
   Exposed-modules: 
-                 -- A class generalizing different levels of monad-par functionality:
-                   Control.Monad.Par.Class
+           -- A class generalizing different levels of monad-par functionality:
+           Control.Monad.Par.Class
 
-                 -- A class providing unsafe functionality:
-                 , Control.Monad.Par.Unsafe
+           -- A class providing unsafe functionality:
+           , Control.Monad.Par.Unsafe
 
   Build-depends: base >= 4 && < 5
                , deepseq >= 1.1

monad-par/Control/Monad/Par.hs

@@ -1,16 +1,13 @@
 
-{-| (NOTE: This module reexports a default Par scheduler.  A generic
-    interface can be found in "Control.Monad.Par.Class" and other
-    schedulers, sometimes with different capabilities, can be found in
-    "Control.Monad.Par.Scheds".)
-
-  The @monad-par@ package provides a family of @Par@ monads, for speeding up pure
-  computations using parallel processors.  They cannot be used for
-  speeding up computations that use IO (for that, see
-  @Control.Concurrent@).  The result of a given @Par@ computation is
-  always the same - ie. it is deterministic, but the computation may
-  be performed more quickly if there are processors available to
-  share the work.
+{-|
+
+  The @monad-par@ package provides a family of @Par@ monads, for
+  speeding up pure computations using parallel processors.  (for a similar
+  programming model for use with @IO@, see "Control.Monad.Par.IO".)
+
+  The result of a given @Par@ computation is always the same - i.e. it
+  is deterministic, but the computation may be performed more quickly
+  if there are processors available to share the work.
 
   For example, the following program fragment computes the values of
   @(f x)@ and @(g x)@ in parallel, and returns a pair of their results:
@@ -69,17 +66,27 @@
   parallel work are only created by @fork@ and a few other
   combinators.
 
-  The implementation is based on a work-stealing scheduler that
-  divides the work as evenly as possible between the available
-  processors at runtime.
+  The default implementation is based on a work-stealing scheduler
+  that divides the work as evenly as possible between the available
+  processors at runtime.  Other schedulers are available that are
+  based on different policies and have different performance
+  characteristics.  To use one of these other schedulers, just import
+  its module instead of "Control.Monad.Par":
+
+  * "Control.Monad.Par.Scheds.Trace"
+
+  * "Control.Monad.Par.Scheds.Sparks"
 
   For more information on the programming model, please see these sources:
 
-      * The wiki/tutorial (<http://www.haskell.org/haskellwiki/Par_Monad:_A_Parallelism_Tutorial>)
+      * The wiki\/tutorial (<http://www.haskell.org/haskellwiki/Par_Monad:_A_Parallelism_Tutorial>)
+
       * The original paper (<http://www.cs.indiana.edu/~rrnewton/papers/haskell2011_monad-par.pdf>)
+
       * Tutorial slides (<http://community.haskell.org/~simonmar/slides/CUFP.pdf>)
-      * Other slides: <http://www.cs.ox.ac.uk/ralf.hinze/WG2.8/28/slides/simon.pdf>, 
-                      <http://www.cs.indiana.edu/~rrnewton/talks/2011_HaskellSymposium_ParMonad.pdf>
+
+      * Other slides: (<http://www.cs.ox.ac.uk/ralf.hinze/WG2.8/28/slides/simon.pdf>,
+                      <http://www.cs.indiana.edu/~rrnewton/talks/2011_HaskellSymposium_ParMonad.pdf>)
 
  -}