diff --git a/Control/Concurrent/Forkable.hs b/Control/Concurrent/Forkable.hs new file mode 100644 --- /dev/null +++ b/Control/Concurrent/Forkable.hs @@ -0,0 +1,111 @@ +-- Copyright 2010 Google Inc. +-- +-- Author: David Anderson +-- +-- See LICENSE and forkable-monad.cabal for authorship and licensing +-- information. + +-- | This module defines a generic version of @Control.Concurrent@'s +-- 'C.forkIO', which can directly run some complex monadic actions as +-- well as plain 'IO' actions. +-- +-- @Control.Concurrent@'s 'C.forkIO' accepts an 'IO' computation only, +-- and requires the caller to reconstruct the full monadic stack by +-- hand in the new thread. In contrast, this module's 'forkIO' runs a +-- computation in the same monad as the parent thread, transparently +-- transplanting the monad stack to the new thread. +-- +-- For example, the following code which uses @Control.Concurrent@'s +-- 'C.forkIO': +-- +-- > type MyMonad = ReaderT Int (StateT String IO) +-- > +-- > forkAndDo :: MyMonad ThreadId +-- > forkAndDo = do +-- > r <- ask +-- > s <- lift get +-- > liftIO $ forkIO $ (runStateT (runReaderT forkedDo r) s >> return ()) +-- > +-- > forkedDo :: MyMonad () +-- > forkedDo = liftIO $ putStrLn "forkedDo running" +-- +-- can be reexpressed with this module's 'forkIO' as: +-- +-- > type MyMonad = ReaderT Int (StateT String IO) +-- > +-- > forkAndDo :: MyMonad ThreadId +-- > forkAndDo = forkIO forkedDo +-- > +-- > forkedDo :: MyMonad () +-- > forkedDo = liftIO $ putStrLn "forkedDo running" +-- +-- 'forkIO' can operate on any monad that is an instance of +-- 'ForkableMonad'. 'ForkableMonad' instances are defined for +-- 'ReaderT' and 'StateT', as well as 'IO'. Here is the precise +-- meaning of \"transplant\" for each of these: +-- +-- * 'IO' requires no special work, since @Control.Concurrent@'s +-- 'C.forkIO' already provides the \"transplanting\" of an 'IO' +-- action to a new thread. +-- +-- * 'ReaderT' makes the parent thread's environment available for +-- consultation in the new thread. +-- +-- * 'StateT' makes a /copy/ of the parent thread's state available +-- in the new thread. The states in the two threads are not +-- linked, so it is expected that they will diverge as each thread +-- updates its own copy of the state. +-- +-- Other standard transformers (notably @WriterT@, @ErrorT@ and +-- @RWST@) do not have an instance defined, because those instances +-- can only be defined through data loss. +-- +-- For example, the current output of a @Writer@ cannot be accessed +-- from within the monad, so the best that can be done is to create a +-- new pristine @Writer@ state for the new thread, and to discard all +-- data written in that thread when the thread terminates. +-- +-- If you want to use 'forkIO' on a monad stack that includes one of +-- these lossy monads, you will need to define the 'ForkableMonad' +-- instances yourself. The same goes for any custom monads you may +-- have in the stack. +-- +-- This module reexports @Control.Concurrent@ overlayed with the +-- generic 'forkIO', so you can simply change your import from +-- @Control.Concurrent@ to @Control.Concurrent.Forkable@ to use this +-- module's 'forkIO' in your existing concurrent code. +module Control.Concurrent.Forkable + ( ForkableMonad (forkIO) + , module Control.Concurrent + ) where + +import qualified Control.Concurrent as C +import Control.Concurrent hiding (forkIO) +import Control.Monad.Reader +import Control.Monad.State + +class (MonadIO m) => ForkableMonad m where + -- | Spark off a new thread to run the monadic computation passed + -- as the first argument, and return the 'ThreadId' of the newly + -- created thread. + -- + -- The new thread will run the computation using the same monadic + -- context as the parent thread. + -- + -- As a convenience, this forkIO accepts a computation returning + -- any value, not just unit. This value is discarded when the + -- computation terminates. + forkIO :: m a -> m C.ThreadId + +instance ForkableMonad IO where + forkIO act = C.forkIO (act >> return ()) + +instance (ForkableMonad m) => ForkableMonad (ReaderT r m) where + forkIO act = do + env <- ask + lift $ forkIO (runReaderT act env) + +instance (ForkableMonad m) => ForkableMonad (StateT s m) where + forkIO act = do + st <- get + lift $ forkIO (runStateT act st) diff --git a/LICENSE b/LICENSE new file mode 100644 --- /dev/null +++ b/LICENSE @@ -0,0 +1,30 @@ +Copyright David Anderson 2010 + +All rights reserved. + +Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions are met: + + * Redistributions of source code must retain the above copyright + notice, this list of conditions and the following disclaimer. + + * Redistributions in binary form must reproduce the above + copyright notice, this list of conditions and the following + disclaimer in the documentation and/or other materials provided + with the distribution. + + * Neither the name of David Anderson nor the names of other + contributors may be used to endorse or promote products derived + from this software without specific prior written permission. + +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. diff --git a/Setup.hs b/Setup.hs new file mode 100644 --- /dev/null +++ b/Setup.hs @@ -0,0 +1,3 @@ +#!/usr/bin/env runhaskell +import Distribution.Simple +main = defaultMain diff --git a/forkable-monad.cabal b/forkable-monad.cabal new file mode 100644 --- /dev/null +++ b/forkable-monad.cabal @@ -0,0 +1,57 @@ +-- The name of the package. +Name: forkable-monad + +-- The package version. See the Haskell package versioning policy +-- (http://www.haskell.org/haskellwiki/Package_versioning_policy) for +-- standards guiding when and how versions should be incremented. +Version: 0.1 + +-- A short (one-line) description of the package. +Synopsis: An implementation of forkIO for monad stacks. + +Description: + This module defines a more generic version of Control.Concurrent's + forkIO, which can directly run some complex monadic actions as well + as plain IO actions. + + +-- URL for the project homepage or repository. +Homepage: http://code.google.com/p/forkable-monad/ + +-- The license under which the package is released. +License: BSD3 + +-- The file containing the license text. +License-file: LICENSE + +-- The package copyright. +Copyright: Google Inc. 2010 + +-- The package author(s). +Author: David Anderson + +-- An email address to which users can send suggestions, bug reports, +-- and patches. +Maintainer: dave@natulte.net + +-- Stability of the pakcage (experimental, provisional, stable...) +Stability: Experimental + +Category: Concurrent + +Build-type: Simple + +-- Constraint on the version of Cabal needed to build this package. +Cabal-version: >=1.2 + +Library + -- Modules exported by the library. + Exposed-modules: Control.Concurrent.Forkable + + -- Packages needed in order to build this package. + Build-depends: base >3.0 && <4.3, + mtl >=1.1 && <1.2 + + -- Compiler options, for normal and profiling builds. + Ghc-options: -Wall + Ghc-prof-options: -auto-all