úÎb·a     #Bas van Dijk <v.dijk.bas@gmail.com>$Regions do not have an instance for  since that would break the (safety guarantees. (Think about lifting forkIO into a region!) However  = and other operations on regions do need the ability to lift &control operations. This is where the  class comes in. This class is identical to  but its  method is (not exported by this module. So user can'!t accidentally break the safety.  Note that a  7 is an instance of this class. For the rest there is a  catch-all  instance  m =>  m. QA type used to tag regions in which locally created handles (handles tagged with ) can be used. +Note than any handle which is created in a RegionT (Local s) can be used outside that region ( RegionT s) and visa versa  (except for -tagged handles). A  LocalRegion< is used to tag regional handles which are created locally. An example is the LocalPtr in the alloca function from the regional-pointers package:   *alloca :: (Storable a, MonadControlIO pr) " => (forall sl. LocalPtr a ( sl s) -> RegionT ( s) pr b)  -> RegionT s pr b The finalisation of the LocalPtr is not performed by the regions library but is handled locally by alloca instead. The type variable sl:, which is only quantified over the continuation, ensures !that locally opened resources don' t escape. The  RootRegion is the ancestor of any region. It'6s primary purpose is to tag regional handles which don't have an associated 1finalizer. For example the standard file handles stdin, stdout and stderr 5which are opened on program startup and which shouldn't be closed when a region #terminates. Another example is the nullPtr! which is a memory pointer which doesn'(t point to any allocated memory so doesn't need to be freed. The AncestorRegion8 class is used to relate the region in which a resource Pwas opened to the region in which it is used. Take the following operation from the safer-file-handles package as an example:  hFileSize :: (pr `AncestorRegion`> cr, MonadIO cr) => RegionalFileHandle ioMode pr -> cr IntegerThe AncestorRegion class defines the parent /% child relationship between regions. The constraint    pr `AncestorRegion` cr is satisfied if and only if cr is a sequence of zero or more "  s" (with varying s ) applied to pr, in other words, if cr is an (improper) nested subregion of pr. The class constraint InternalAncestorRegion pr cr! serves two purposes. First, the  instances of InternalAncestorRegion- do the type-level recursion that implements Qthe relation specified above. Second, since it is not exported, user code cannot add new instances of . (as these would have to be made instances of InternalAncestorRegion&, too), effectively turning it into a  closed class.  Duplicate an h in the parent region. This h will usually be some type of regional handle. 3For example, suppose you run the following region:   runRegionT $ do $Inside this region you run a nested child region like:    r1hDup <- runRegionT $ do /Now in this child region you open the resource r1:    r1h < - open r1  ...yielding the regional handle r1h . Note that:  3r1h :: RegionalHandle (RegionT cs (RegionT ps ppr))where cs is bound by the inner (child)  runRegionT and ps is bound by the outer (parent)  runRegionT. 6Suppose you want to use the resulting regional handle r1h in the parent region. You can' t simply  return r1h because then the type variable cs, escapes the inner region. HHowever, if you duplicate the regional handle you can safely return it.    r1hDup < - dup r1h  return r1hDup  Note that )r1hDup :: RegionalHandle (RegionT ps ppr) 4Back in the parent region you can safely operate on r1hDup. A handle to a  4 that allows you to duplicate it to a parent region using . JDuplicating a finalizer means that instead of it being performed when the Mcurrent region terminates it is performed when the parent region terminates.  An > computation that closes or finalizes a resource. For example  "hClose someHandle" or " free somePtr". A  > paired with its reference count which defines how many times ( it has been registered in some region.  MA monad transformer in which scarce resources can be opened. When the region Aterminates, all opened resources will be closed automatically. It's a type error Eto return an opened resource from the region. The latter ensures no I/O with closed resources is possible.   Register the  / in the region. When the region terminates all .registered finalizers will be perfomed if they're not duplicated to a parent region. \Note that finalizers are run in LIFO order (Last In First Out). So executing the following:   runRegionT $ do  _ <- onExit $ putStrLn " finalizer 1"  _ <- onExit $ putStrLn " finalizer 2"  return () yields:   finalizer 2  finalizer 1 *Execute a region inside its parent region pr. HAll resources which have been opened in the given region and which haven't been duplicated using 6, will be closed on exit from this function wether by /normal termination or by raising an exception. QAlso 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 s7 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.) @Note that it is possible to run a region inside another region.   Convert a  region to a regular region. 7This function is unsafe because it allows you to use a -tagged handle outside its  region. Lift a callCC operation to the new monad. +Transform the computation inside a region. Lift a  catchError operation to the new monad.   #Bas van Dijk <v.dijk.bas@gmail.com>   #Bas van Dijk <v.dijk.bas@gmail.com>  #Bas van Dijk <v.dijk.bas@gmail.com>           !""#$%& regions-0.11Control.Monad.Trans.Region!Control.Monad.Trans.Region.Unsafe!Control.Monad.Trans.Region.OnExit#Control.Monad.Trans.Region.InternalRegionControlIOunsafeLiftControlIOLocal LocalRegion RootRegionAncestorRegionDupdupFinalizerHandle FinalizerRegionTonExit runRegionTunsafeStripLocalunsafeLiftControlunsafeControlIOunsafeLiftIOOpunsafeLiftIOOp_ liftCallCC mapRegionT liftCatchmonad-control-0.2.0.3Control.Monad.IO.ControlMonadControlIOInternalAncestorRegionRefCntghc-prim GHC.TypesIORefCountedFinalizer unRegionTcopy increment