diff --git a/CONTRIBUTORS b/CONTRIBUTORS new file mode 100644 --- /dev/null +++ b/CONTRIBUTORS @@ -0,0 +1,6 @@ +* Oleg Kiselyov and Chung-chieh Shan + For coming up with the original idea of "lightweight monadic regions". + +* Ben Franksen + For rewriting the overly complicated ParentOf class and related instances + to something really clean and simple exploiting TypeFamilies. diff --git a/Control/Monad/Trans/Region.hs b/Control/Monad/Trans/Region.hs --- a/Control/Monad/Trans/Region.hs +++ b/Control/Monad/Trans/Region.hs @@ -1,7 +1,7 @@ ------------------------------------------------------------------------------- -- | -- Module : Control.Monad.Trans.Region --- Copyright : (c) 2009-2010 Bas van Dijk +-- Copyright : (c) 2009-2011 Bas van Dijk -- License : BSD3 (see the file LICENSE) -- Maintainer : Bas van Dijk -- @@ -18,6 +18,8 @@ -- * Running regions , runRegionT + + , RegionControlIO -- * Duplication , Dup(dup) diff --git a/Control/Monad/Trans/Region/Internal.hs b/Control/Monad/Trans/Region/Internal.hs --- a/Control/Monad/Trans/Region/Internal.hs +++ b/Control/Monad/Trans/Region/Internal.hs @@ -9,12 +9,13 @@ , UndecidableInstances -- For the AncestorRegion instances. , FlexibleInstances -- ,, ,, ,, , OverlappingInstances -- ,, ,, ,, + , FlexibleContexts -- For unsafeLiftControl #-} ------------------------------------------------------------------------------- -- | -- Module : Control.Monad.Trans.Region.Internal --- Copyright : (c) 2009-2010 Bas van Dijk +-- Copyright : (c) 2009-2011 Bas van Dijk -- License : BSD3 (see the file LICENSE) -- Maintainer : Bas van Dijk -- @@ -53,6 +54,13 @@ -- ** Local regions , LocalRegion, Local, unsafeStripLocal + -- * MonadTransControl & MonadControlIO + , RegionControlIO, unsafeLiftControlIO + , unsafeLiftControl + , unsafeControlIO + , unsafeLiftIOOp + , unsafeLiftIOOp_ + -- * Utilities for writing monadic instances , liftCallCC , mapRegionT @@ -67,7 +75,7 @@ -- from base: import Prelude ( (+), (-), seq ) import Control.Applicative ( Applicative, Alternative ) -import Control.Monad ( Monad, return, when, forM_, MonadPlus ) +import Control.Monad ( Monad, return, when, forM_, join, liftM, MonadPlus, ) import Control.Monad.Fix ( MonadFix ) import Control.Exception ( bracket ) import System.IO ( IO ) @@ -83,8 +91,8 @@ #endif -- from monad-control: -import Control.Monad.Trans.Control ( MonadTransControl ) -import Control.Monad.IO.Control ( MonadControlIO, controlIO ) +import Control.Monad.Trans.Control ( Run, RunInBase, liftControl ) +import Control.Monad.IO.Control ( MonadControlIO, liftControlIO ) -- from transformers: import Control.Monad.Trans.Class ( MonadTrans, lift ) @@ -124,9 +132,7 @@ , MonadPlus , MonadFix , MonadTrans - , MonadTransControl , MonadIO - , MonadControlIO ) unRegionT ∷ RegionT s pr α → ReaderT (IORef [RefCountedFinalizer]) pr α @@ -202,8 +208,8 @@ Note that it is possible to run a region inside another region. -} -runRegionT ∷ MonadControlIO pr ⇒ (∀ s. RegionT s pr α) → pr α -runRegionT r = bracketIO before after thing +runRegionT ∷ RegionControlIO pr ⇒ (∀ s. RegionT s pr α) → pr α +runRegionT r = unsafeLiftIOOp (bracket before after) thing where before = newIORef [] thing hsIORef = runReaderT (unRegionT r) hsIORef @@ -218,11 +224,7 @@ let refCnt' = refCnt - 1 in (refCnt', refCnt') -bracketIO ∷ MonadControlIO m ⇒ IO α → (α → IO ()) → (α → m β) → m β -bracketIO before after thing = controlIO $ \runInIO → - bracket before after (runInIO ∘ thing) - -------------------------------------------------------------------------------- -- * Duplication -------------------------------------------------------------------------------- @@ -399,8 +401,56 @@ handle outside its 'Local' region. -} unsafeStripLocal ∷ RegionT (Local s) pr α → RegionT s pr α -unsafeStripLocal = RegionT ∘ unRegionT +unsafeStripLocal = RegionT ∘ unRegionT + +-------------------------------------------------------------------------------- +-- * MonadTransControl & MonadControlIO +-------------------------------------------------------------------------------- + +{-| +Regions do not have an instance for 'MonadControlIO' since that would break the +safety guarantees. (Think about lifting 'forkIO' into a region!) + +However 'runRegionT' and other operations on regions do need the ability to lift +control operations. This is where the 'RegionControlIO' class comes in. This +class is identical to `MonadControlIO` but its 'unsafeLiftControlIO' method is +not exported by this module. So user can't accidentally break the safety. + +Note that a 'RegionT' is an instance of this class. For the rest there is a +catch-all @instance 'MonadControlIO' m => 'RegionControlIO' m@. +-} +class MonadIO m ⇒ RegionControlIO m where + unsafeLiftControlIO ∷ (RunInBase m IO → IO α) → m α + +instance RegionControlIO pr ⇒ RegionControlIO (RegionT s pr) where + unsafeLiftControlIO f = + unsafeLiftControl $ \runInPr → + unsafeLiftControlIO $ \runInBase → + let run = liftM (join ∘ lift) ∘ runInBase ∘ runInPr + in f run + +instance MonadControlIO m ⇒ RegionControlIO m where + unsafeLiftControlIO = liftControlIO + +-------------------------------------------------------------------------------- + +unsafeLiftControl ∷ Monad pr ⇒ (Run (RegionT s) → pr α) → RegionT s pr α +unsafeLiftControl f = RegionT $ liftControl $ \runReader → + f $ liftM RegionT ∘ runReader ∘ unRegionT + +unsafeControlIO ∷ RegionControlIO m ⇒ (RunInBase m IO → IO (m α)) → m α +unsafeControlIO = join ∘ unsafeLiftControlIO + +unsafeLiftIOOp ∷ RegionControlIO m + ⇒ ((α → IO (m β)) → IO (m γ)) + → ((α → m β) → m γ) +unsafeLiftIOOp f = \g → unsafeControlIO $ \runInIO → f $ runInIO ∘ g + +unsafeLiftIOOp_ ∷ RegionControlIO m + ⇒ (IO (m α) → IO (m β)) + → ( m α → m β) +unsafeLiftIOOp_ f = \m → unsafeControlIO $ \runInIO → f $ runInIO m -------------------------------------------------------------------------------- -- * Utilities for writing monadic instances diff --git a/Control/Monad/Trans/Region/OnExit.hs b/Control/Monad/Trans/Region/OnExit.hs --- a/Control/Monad/Trans/Region/OnExit.hs +++ b/Control/Monad/Trans/Region/OnExit.hs @@ -1,7 +1,7 @@ ------------------------------------------------------------------------------- -- | -- Module : Control.Monad.Trans.Region.OnExit --- Copyright : (c) 2009-2010 Bas van Dijk +-- Copyright : (c) 2009-2011 Bas van Dijk -- License : BSD3 (see the file LICENSE) -- Maintainer : Bas van Dijk -- diff --git a/Control/Monad/Trans/Region/Unsafe.hs b/Control/Monad/Trans/Region/Unsafe.hs --- a/Control/Monad/Trans/Region/Unsafe.hs +++ b/Control/Monad/Trans/Region/Unsafe.hs @@ -1,13 +1,23 @@ ------------------------------------------------------------------------------- -- | -- Module : Control.Monad.Trans.Region.Unsafe --- Copyright : (c) 2009-2010 Bas van Dijk +-- Copyright : (c) 2009-2011 Bas van Dijk -- License : BSD3 (see the file LICENSE) -- Maintainer : Bas van Dijk -- -- -------------------------------------------------------------------------------- -module Control.Monad.Trans.Region.Unsafe ( unsafeStripLocal ) where +module Control.Monad.Trans.Region.Unsafe + ( -- * Local regions + unsafeStripLocal -import Control.Monad.Trans.Region.Internal ( unsafeStripLocal ) + -- * MonadTransControl & MonadControlIO + , unsafeLiftControlIO + , unsafeLiftControl + , unsafeControlIO + , unsafeLiftIOOp + , unsafeLiftIOOp_ + ) where + +import Control.Monad.Trans.Region.Internal diff --git a/LICENSE b/LICENSE --- a/LICENSE +++ b/LICENSE @@ -1,4 +1,4 @@ -Copyright (c) 2009-2010 Bas van Dijk +Copyright (c) 2009-2011 Bas van Dijk All rights reserved. diff --git a/NEWS b/NEWS new file mode 100644 --- /dev/null +++ b/NEWS @@ -0,0 +1,154 @@ +0.9 + +(Relased on: Wed Mar 9 12:20:05 UTC 2011) + +* Removed Control.Monad.Trans.Region.Concurrent + The fork functions contained bugs which could not be fixed. + +* Removed Data.RegionRef + I always considered this module a bit of a wart. + +* Switch from monad-peel to monad-control. + +* Added support for local regions + Primarily needed for the alloca functions from the regional-pointers package. + + +0.8.1 + +(Released on: Mon Jan 17 22:04:15 UTC 2011) + +* Fixed bug: Forked threads should have the same masked state has their parents. + +* Added forkIOUnmasked. + +* Derived MonadTransPeel instance for RegionT. + + +0.8 + +(Released on: Sat Nov 6 15:56:27 UTC 2010) + +* Released during BelHac 2010! + +* Replaced ParentOf class with the more understandable, + easier to implement and safer AncestorRegion class. + (Contributed by Ben Franksen) + + Also moved the class from its own module to the main: + Control.Monad.Trans.Region module. + +* Exported fork*TopRegion functions from their own dedicated module: + Control.Monad.Trans.Region.Concurrent. + +* Use MonadPeelIO instead of MonadCatchIO. + +* Removed TopRegion and runTopRegion and + renamed the fork functions accordingly. + +* Renamed CloseAction to Finalizer and + CloseHandle to FinalizerHandle. + +* Added the RootRegion (empty) datatype which is defined as the + ancestor of any region. + + +0.7.0.1 + +(Released on: Sat Sep 11 14:17:48 UTC 2010) + +* Added strictness flags to the arguments of the Handle data constructor. + +* Fix haddock link. + + +0.7 + +(Released on: Wed Sep 1 20:11:41 UTC 2010) + +* Renamed forkTopRegion to forkIOTopRegion + Also added forkOSTopRegion and forkOnIOTopRegion. + + +0.6.0.1 + +(Released on: Wed Jun 16 13:45:27 UTC 2010) + +* Removed outdated documentation. + + +0.6 + +(Released on: Wed Jun 16 09:11:23 UTC 2010) + +* Major change: removed the Resource class in favor of the much + simpler 'onExit' function. + +* Renamed Control.Monad.Trans.Region.Close to + Control.Monad.Trans.Region.OnExit. + + +0.5 + +(Released on: Sun May 2 20:24:19 UTC 2010) + +* Renamed openResource and closeResource to open and close + respectively The intention is that Control.Resource should be + imported qualified. + +* Updated dependencies + transformers >= 0.2 && < 0.3 + MonadCatchIO-transformers >= 0.2 && < 0.3 + base-unicode-symbols >= 0.1.1 && < 0.3 + + +0.4 + +(Released on: Thu Feb 4 10:17:47 UTC 2010) + +* Added Data.RegionRef. + +* Moved the Resource class to its own module Control.Resource. + +* Depend on more compatible versions of MonadCatchIO-transformers. + +* Defined and exported liftCallCC. + + +0.3 + +(Released on: Sat Jan 23 14:25:08 UTC 2010) + +* Add 'mapInternalHandle'. + +* Export the 'Dup' and 'ParentOf' classes from + 'Control.Monad.Trans.Region'. + + +0.2 + +(Released on: Thu Jan 7 14:14:15 UTC 2010) + +* Renamed module Control.Monad.Trans.Region.Internal to + Control.Monad.Trans.Region.Unsafe. + +* Export only the unsafe things from Control.Monad.Trans.Region.Unsafe. + +* Removed resource type from RegionT which prevented opening different + types of resources in the same region. + + +0.1.0.1 + +(Released on: Wed Dec 23 13:42:48 UTC 2009) + +* Depend on base-unicode-symbols instead of unicode-symbols. + +* Tested with base 4.2. + + +0.1 + +(Released on: Mon Dec 21 09:46:51 UTC 2009) + +* Initial release. diff --git a/README.markdown b/README.markdown new file mode 100644 --- /dev/null +++ b/README.markdown @@ -0,0 +1,25 @@ +This package provides the region monad transformer. Scarce resources +like files, memory pointers or USB devices for example can be opened +in a region. When the region terminates, all opened resources will be +automatically closed. The main advantage of regions is that the opened +resources can not be returned from the region which ensures no I/O +with closed resources is possible. + +The primary technique used in this package is called "Lightweight +monadic regions" which was [invented][1] by Oleg Kiselyov and +Chung-chieh Shan. + +Also see the [regions-mtl] and [regions-monadstf] packages which +provide instances for the classes in the respected monad transformers +packages. + +For an example on how to use this library see the +[safer-file-handles], [usb-safe] or [regional-pointers] packages. + +[1]: http://okmij.org/ftp/Haskell/regions.html#light-weight + +[regions-mtl]: http://hackage.haskell.org/package/regions-mtl +[regions-monadstf]: http://hackage.haskell.org/package/regions-monadstf +[safer-file-handles]: http://hackage.haskell.org/package/safer-file-handles +[usb-safe]: http://hackage.haskell.org/package/usb-safe +[regional-pointers]: http://hackage.haskell.org/package/regional-pointers diff --git a/regions.cabal b/regions.cabal --- a/regions.cabal +++ b/regions.cabal @@ -1,12 +1,14 @@ name: regions -version: 0.9 +version: 0.11 cabal-version: >=1.6 build-type: Simple license: BSD3 license-file: LICENSE -copyright: 2009-2010 Bas van Dijk +copyright: 2009-2011 Bas van Dijk author: Bas van Dijk maintainer: Bas van Dijk +homepage: https://github.com/basvandijk/regions/ +bug-reports: https://github.com/basvandijk/regions/issues stability: experimental category: Control, Monadic Regions synopsis: Provides the region monad for safely opening and working with @@ -30,13 +32,15 @@ For an example on how to use this library see the @safer-file-handles@, @usb-safe@ or @regional-pointers@ packages. +extra-source-files: README.markdown, NEWS, CONTRIBUTORS + source-repository head - Type: darcs - Location: http://code.haskell.org/~basvandijk/code/regions + Type: git + Location: git://github.com/basvandijk/regions.git Library GHC-Options: -Wall - build-depends: base >= 4 && < 4.4 + build-depends: base >= 4 && < 4.5 , base-unicode-symbols >= 0.1.1 && < 0.3 , transformers >= 0.2 && < 0.3 , monad-control >= 0.2 && < 0.3