| regions-0.1.0.1: Provides the region monad for safely opening and working with
scarce resources. | Source code | Contents | Index |
|
Control.Monad.Trans.Region | Maintainer | Bas van Dijk <v.dijk.bas@gmail.com> |
|
|
|
|
|
Description |
This modules implements a technique called "Lightweight monadic regions"
invented by Oleg Kiselyov and Chung-chieh Shan
See: http://okmij.org/ftp/Haskell/regions.html#light-weight
|
|
Synopsis |
|
|
|
|
Regions
|
|
data RegionT resource s pr α | Source |
|
A monad transformer in which resources of type resource can be opened
which are automatically closed when the region terminates.
Note that regions can be nested. pr (for parent region) is a monad which is
usually the region which is running this region. However when you are running a
TopRegion the parent region will be IO.
| Instances | |
|
|
Running regions
|
|
|
:: (Resource resource, MonadCatchIO pr) | | => forall s. RegionT resource s pr α | Computation in the parent region which executes the given
region.
| -> pr α | | Execute a region inside its parent region pr.
All resources which have been opened in the given region using open, and which
haven't been duplicated using dup, will be closed on exit from this function
wether by normal termination or by raising an exception.
Also all resources which have been duplicated to this region from a child region
are closed on exit if they haven't been duplicated themselves.
Note the type variable s of the region wich is only quantified over the region
itself. This ensures that all values, having a type containing s, can not
be returned from this function. (Note the similarity with the ST monad.)
An example of such a value is a RegionalHandle. Regional handles are created by
opening a resource in a region using open. Regional handles are parameterized by
the region in which they were created. So regional handles have this s in their
type. This ensures that these regional handles, which may have been closed on exit
from this function, can't be returned from this function. This ensures you can
never do any IO with a closed regional handle.
Note that it is possible to run a region inside another region.
|
|
|
|
A region which has IO as its parent region which enables it to be:
|
|
|
:: Resource resource | | => forall s. TopRegion resource s α | An IO computation which executes the given region.
| -> IO α | | Convenience funtion for running a top-level region in IO.
Note that: runTopRegion = runRegionT
|
|
|
|
:: (Resource resource, MonadIO pr) | | => TopRegion resource s () | A regional computation that executes the given region in a
new thread and returns the ThreadId of this new thread.
| -> RegionT resource s pr ThreadId | | Return a region which executes the given top-level region in a new thread.
Note that the forked region has the same type variable s as the resulting
region. This means that all values which can be referenced in the resulting
region (like RegionalHandles for example) can also be referenced in the forked
region.
For example the following is allowed:
runRegionT $ do
regionalHndl <- open resource
threadId <- forkTopRegion $ doSomethingWith regionalHndl
doSomethingElseWith regionalHndl
Note that the regionalHndl and all other resources opened in the current
thread are closed only when the current thread or the forked thread terminates
whichever comes last.
|
|
|
Opening resources
|
|
data RegionalHandle resource r | Source |
|
A handle to an opened resource parameterized by the resource and the
region r in which it was created.
| Instances | |
|
|
|
:: (Resource resource, MonadCatchIO pr) | | => resource | A regional computation that returns a regional handle to the given
opened resource parameterized by the region itself.
| -> RegionT resource s pr (RegionalHandle resource (RegionT resource s pr)) | | Open the given resource in a region yielding a regional handle to it.
Note that the returned regional handle is parameterized by the region in which
it was created. This ensures that regional handles can never escape their
region. And it also allows operations on regional handles to be executed in a
child region of the region in which the regional handle was created.
Note that if you do wish to return a regional handle from the region in which
it was created you have to duplicate the handle by applying dup to it.
|
|
|
|
:: (Resource resource, MonadCatchIO pr) | | => resource | Continuation function.
| -> forall s. RegionalHandle resource (RegionT resource s pr) -> RegionT resource s pr α | A computation which runs a child region which opens the given
resource and applies the given continuation function to the
resulting regional handle.
| -> pr α | | A convenience function which opens the given resource, applies the given
continuation function to the resulting regional handle and runs the resulting
region.
Note that: with dev f = runRegionT (open dev >>= f)
|
|
|
Duplication
|
|
|
:: (Dup α resource, MonadCatchIO ppr) | | => α (RegionT resource cs (RegionT resource ps ppr)) | The child region which returns the thing which can now be used in
the parent region.
| -> RegionT resource cs (RegionT resource ps ppr) (α (RegionT resource ps ppr)) | |
|
|
Produced by Haddock version 2.6.0 |