diff --git a/Control/Monad/Par/Class.hs b/Control/Monad/Par/Class.hs --- a/Control/Monad/Par/Class.hs +++ b/Control/Monad/Par/Class.hs @@ -1,40 +1,40 @@ {-# LANGUAGE MultiParamTypeClasses, FunctionalDependencies, CPP, - FlexibleInstances, UndecidableInstances - #-} + FlexibleInstances, UndecidableInstances #-} -- 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 + For more documentation of the programming model, see - * The "Control.Monad.Par" module in the @monad-par@ package. - * The wiki/tutorial () - * The original paper () - * Tutorial slides () - * Other slides: , - + * The "Control.Monad.Par" module in the @monad-par@ package. + * The wiki\/tutorial () + + * The original paper () + + * Tutorial slides () + + * Other slides (, ) + -} --- +-- -module Control.Monad.Par.Class - ( +module Control.Monad.Par.Class + ( -- * Futures ParFuture(..) -- * IVars , ParIVar(..) - + -- RRN: Not releasing this interface until there is a nice implementation of it: -- Channels (Streams) -- , ParChan(..) - , NFData() + , NFData() -- This is reexported. ) where @@ -45,14 +45,14 @@ -- | @ParFuture@ captures the class of Par monads which support -- futures. This level of functionality subsumes @par@/@pseq@ and is -- similar to the "Control.Parallel.Strategies.Eval" monad. --- +-- -- A minimal implementation consists of `spawn_` and `get`. -- However, for monads that are also a member of `ParIVar` it is -- typical to simply define `spawn` in terms of `fork`, `new`, and `put`. class Monad m => ParFuture future m | m -> future where -- | Create a potentially-parallel computation, and return a /future/ -- (or /promise/) that can be used to query the result of the forked - -- computataion. + -- computataion. -- -- > spawn p = do -- > r <- new @@ -63,13 +63,15 @@ -- | 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. - -- + -- -- > spawnP = spawn . return spawnP :: NFData a => a -> m (future a) - + -- Default implementations: spawn p = spawn_ (do x <- p; deepseq x (return x)) spawnP a = spawn (return a) @@ -79,17 +81,17 @@ -- | @ParIVar@ builds on futures by adding full /anyone-writes, anyone-reads/ IVars. -- These are more expressive but may not be supported by all distributed schedulers. --- +-- -- A minimal implementation consists of `fork`, `put_`, and `new`. class ParFuture ivar m => ParIVar ivar m | m -> ivar where -- | Forks a computation to happen in parallel. The forked -- computation may exchange values with other computations using -- @IVar@s. fork :: m () -> m () - + -- | creates a new @IVar@ new :: m (ivar a) - + -- | put a value into a @IVar@. Multiple 'put's to the same @IVar@ -- are not allowed, and result in a runtime error. -- @@ -108,21 +110,21 @@ put_ :: ivar a -> a -> m () -- Extra API routines that have default implementations: - + -- | creates a new @IVar@ that contains a value newFull :: NFData a => a -> m (ivar a) newFull a = deepseq a (newFull_ a) - + -- | creates a new @IVar@ that contains a value (head-strict only) newFull_ :: a -> m (ivar a) newFull_ a = do v <- new - -- This is usually inefficient! + -- This is usually inefficient! put_ v a return v --------------------------------------------------------------------------------- +-------------------------------------------------------------------------------- --- class ParYieldable ?? +-- class ParYieldable ?? -- TODO: I think we should add yield officially: -- Allows other parallel computations to progress. (should not be @@ -156,12 +158,12 @@ -- t1 :: P.Par Int -- If the ParIVar => ParFuture instance exists the following is sufficient: t1 :: (ParFuture v m) => m Int -t1 = do +t1 = do x <- spawn (return 3) get x t2 :: (ParIVar v m) => m Int -t2 = do +t2 = do x <- new put x "hi" return 3 @@ -169,5 +171,5 @@ -- TODO: SPECIALIZE generic routines for the default par monad (and possibly ParRNG)? --- SPECIALISE parMap :: (NFData b) => (a -> b) -> [a] -> Par [b] --- SPECIALISE parMapM :: (NFData b) => (a -> Par b) -> [a] -> Par [b] +-- SPECIALISE parMap :: (NFData b) => (a -> b) -> [a] -> Par [b] +-- SPECIALISE parMapM :: (NFData b) => (a -> Par b) -> [a] -> Par [b] diff --git a/abstract-par.cabal b/abstract-par.cabal --- a/abstract-par.cabal +++ b/abstract-par.cabal @@ -1,5 +1,5 @@ Name: abstract-par -Version: 0.3.1 +Version: 0.3.3 Synopsis: Type classes generalizing the functionality of the 'monad-par' library. @@ -7,27 +7,17 @@ -- 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. +-- 0.3.3 : Minor: doc and formatting changes only. +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 +35,11 @@ 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