libghc-resourcet-doc 0.4.7.1-1build1 / usr / share / doc / libghc-resourcet-doc / html / resourcet.txt

-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Deterministic allocation and freeing of scarce resources.
--   
--   This package was originally included with the conduit package, and has
--   since been split off. For more information, please see
--   <a>http://www.yesodweb.com/book/conduits</a>.
@package resourcet
@version 0.4.7.1


-- | Allocate resources which are guaranteed to be released.
--   
--   For more information, see
--   <a>http://www.yesodweb.com/book/conduits</a>.
--   
--   One point to note: all register cleanup actions live in the
--   <tt>IO</tt> monad, not the main monad. This allows both more efficient
--   code, and for monads to be transformed.
module Control.Monad.Trans.Resource

-- | The Resource transformer. This transformer keeps track of all
--   registered actions, and calls them upon exit (via
--   <a>runResourceT</a>). Actions may be registered via <a>register</a>,
--   or resources may be allocated atomically via <a>allocate</a>.
--   <tt>allocate</tt> corresponds closely to <tt>bracket</tt>.
--   
--   Releasing may be performed before exit via the <a>release</a>
--   function. This is a highly recommended optimization, as it will ensure
--   that scarce resources are freed early. Note that calling
--   <tt>release</tt> will deregister the action, so that a release action
--   will only ever be called once.
--   
--   Since 0.3.0
data ResourceT m a

-- | Convenient alias for <tt>ResourceT IO</tt>.
type ResIO a = ResourceT IO a

-- | A lookup key for a specific release action. This value is returned by
--   <a>register</a> and <a>allocate</a>, and is passed to <a>release</a>.
--   
--   Since 0.3.0
data ReleaseKey

-- | Unwrap a <a>ResourceT</a> transformer, and call all registered release
--   actions.
--   
--   Note that there is some reference counting involved due to
--   <a>resourceForkIO</a>. If multiple threads are sharing the same
--   collection of resources, only the last call to <tt>runResourceT</tt>
--   will deallocate the resources.
--   
--   Since 0.3.0
runResourceT :: MonadBaseControl IO m => ResourceT m a -> m a

-- | Introduce a reference-counting scheme to allow a resource context to
--   be shared by multiple threads. Once the last thread exits, all
--   remaining resources will be released.
--   
--   Note that abuse of this function will greatly delay the deallocation
--   of registered resources. This function should be used with care. A
--   general guideline:
--   
--   If you are allocating a resource that should be shared by multiple
--   threads, and will be held for a long time, you should allocate it at
--   the beginning of a new <tt>ResourceT</tt> block and then call
--   <tt>resourceForkIO</tt> from there.
--   
--   Since 0.3.0
resourceForkIO :: MonadBaseControl IO m => ResourceT m () -> ResourceT m ThreadId

-- | Transform the monad a <tt>ResourceT</tt> lives in. This is most often
--   used to strip or add new transformers to a stack, e.g. to run a
--   <tt>ReaderT</tt>.
--   
--   Note that this function is a slight generalization of <a>hoist</a>.
--   
--   Since 0.3.0
transResourceT :: (m a -> n b) -> ResourceT m a -> ResourceT n b

-- | This function mirrors <tt>join</tt> at the transformer level: it will
--   collapse two levels of <tt>ResourceT</tt> into a single
--   <tt>ResourceT</tt>.
--   
--   Since 0.4.6
joinResourceT :: ResourceT (ResourceT m) a -> ResourceT m a

-- | The express purpose of this transformer is to allow
--   non-<tt>IO</tt>-based monad stacks to catch exceptions via the
--   <a>MonadThrow</a> typeclass.
--   
--   Since 0.3.0
newtype ExceptionT m a
ExceptionT :: m (Either SomeException a) -> ExceptionT m a
runExceptionT :: ExceptionT m a -> m (Either SomeException a)

-- | Same as <a>runExceptionT</a>, but immediately <a>throw</a> any
--   exception returned.
--   
--   Since 0.3.0
runExceptionT_ :: Monad m => ExceptionT m a -> m a

-- | Run an <tt>ExceptionT Identity</tt> stack.
--   
--   Since 0.4.2
runException :: ExceptionT Identity a -> Either SomeException a

-- | Run an <tt>ExceptionT Identity</tt> stack, but immediately
--   <a>throw</a> any exception returned.
--   
--   Since 0.4.2
runException_ :: ExceptionT Identity a -> a

-- | Perform some allocation, and automatically register a cleanup action.
--   
--   This is almost identical to calling the allocation and then
--   <tt>register</tt>ing the release action, but this properly handles
--   masking of asynchronous exceptions.
--   
--   Since 0.3.0
allocate :: MonadResource m => IO a -> (a -> IO ()) -> m (ReleaseKey, a)

-- | Register some action that will be called precisely once, either when
--   <a>runResourceT</a> is called, or when the <a>ReleaseKey</a> is passed
--   to <a>release</a>.
--   
--   Since 0.3.0
register :: MonadResource m => IO () -> m ReleaseKey

-- | Call a release action early, and deregister it from the list of
--   cleanup actions to be performed.
--   
--   Since 0.3.0
release :: MonadIO m => ReleaseKey -> m ()

-- | Unprotect resource from cleanup actions, this allowes you to send
--   resource into another resourcet process and reregister it there. It
--   returns an release action that should be run in order to clean
--   resource or Nothing in case if resource is already freed.
--   
--   Since 0.4.5
unprotect :: MonadIO m => ReleaseKey -> m (Maybe (IO ()))

-- | Perform asynchronous exception masking.
--   
--   This is more general then <tt>Control.Exception.mask</tt>, yet more
--   efficient than <tt>Control.Exception.Lifted.mask</tt>.
--   
--   Since 0.3.0
resourceMask :: MonadResource m => ((forall a. ResourceT IO a -> ResourceT IO a) -> ResourceT IO b) -> m b

-- | A <tt>Monad</tt> which allows for safe resource allocation. In theory,
--   any monad transformer stack included a <tt>ResourceT</tt> can be an
--   instance of <tt>MonadResource</tt>.
--   
--   Note: <tt>runResourceT</tt> has a requirement for a
--   <tt>MonadBaseControl IO m</tt> monad, which allows control operations
--   to be lifted. A <tt>MonadResource</tt> does not have this requirement.
--   This means that transformers such as <tt>ContT</tt> can be an instance
--   of <tt>MonadResource</tt>. However, the <tt>ContT</tt> wrapper will
--   need to be unwrapped before calling <tt>runResourceT</tt>.
--   
--   Since 0.3.0
class (MonadThrow m, MonadUnsafeIO m, MonadIO m, Applicative m) => MonadResource m
liftResourceT :: MonadResource m => ResourceT IO a -> m a

-- | A <tt>Monad</tt> based on some monad which allows running of some
--   <a>IO</a> actions, via unsafe calls. This applies to <a>IO</a> and
--   <a>ST</a>, for instance.
--   
--   Since 0.3.0
class Monad m => MonadUnsafeIO m
unsafeLiftIO :: MonadUnsafeIO m => IO a -> m a

-- | A <tt>Monad</tt> which can throw exceptions. Note that this does not
--   work in a vanilla <tt>ST</tt> or <tt>Identity</tt> monad. Instead, you
--   should use the <a>ExceptionT</a> transformer in your stack if you are
--   dealing with a non-<tt>IO</tt> base monad.
--   
--   Since 0.3.0
class Monad m => MonadThrow m
monadThrow :: (MonadThrow m, Exception e) => e -> m a

-- | Determine if some monad is still active. This is intended to prevent
--   usage of a monadic state after it has been closed. This is necessary
--   for such cases as lazy I/O, where an unevaluated thunk may still refer
--   to a closed <tt>ResourceT</tt>.
--   
--   Since 0.3.0
class Monad m => MonadActive m
monadActive :: MonadActive m => m Bool

-- | A <tt>Monad</tt> which can be used as a base for a <tt>ResourceT</tt>.
--   
--   A <tt>ResourceT</tt> has some restrictions on its base monad:
--   
--   <ul>
--   <li><tt>runResourceT</tt> requires an instance of <tt>MonadBaseControl
--   IO</tt>. * <tt>MonadResource</tt> requires an instance of
--   <tt>MonadThrow</tt>, <tt>MonadUnsafeIO</tt>, <tt>MonadIO</tt>, and
--   <tt>Applicative</tt>.</li>
--   </ul>
--   
--   While any instance of <tt>MonadBaseControl IO</tt> should be an
--   instance of the other classes, this is not guaranteed by the type
--   system (e.g., you may have a transformer in your stack with does not
--   implement <tt>MonadThrow</tt>). Ideally, we would like to simply
--   create an alias for the five type classes listed, but this is not
--   possible with GHC currently.
--   
--   Instead, this typeclass acts as a proxy for the other five. Its only
--   purpose is to make your type signatures shorter.
--   
--   Note that earlier versions of <tt>conduit</tt> had a typeclass
--   <tt>ResourceIO</tt>. This fulfills much the same role.
--   
--   Since 0.3.2
type MonadResourceBase m = (MonadBaseControl IO m, MonadThrow m, MonadUnsafeIO m, MonadIO m, Applicative m)

-- | Indicates either an error in the library, or misuse of it (e.g., a
--   <tt>ResourceT</tt>'s state is accessed after being released).
--   
--   Since 0.3.0
data InvalidAccess
InvalidAccess :: String -> InvalidAccess
functionName :: InvalidAccess -> String
class MonadBase b m => MonadBaseControl (b :: * -> *) (m :: * -> *) | m -> b

-- | The internal state held by a <tt>ResourceT</tt> transformer.
--   
--   Since 0.4.6
type InternalState = IORef ReleaseMap

-- | Get the internal state of the current <tt>ResourceT</tt>.
--   
--   Since 0.4.6
getInternalState :: Monad m => ResourceT m InternalState

-- | Unwrap a <tt>ResourceT</tt> using the given <tt>InternalState</tt>.
--   
--   Since 0.4.6
runInternalState :: ResourceT m a -> InternalState -> m a
withInternalState :: (InternalState -> m a) -> ResourceT m a
instance Typeable ReleaseKey
instance Typeable InvalidAccess
instance (Monoid w, MonadActive m) => MonadActive (WriterT w m)
instance MonadActive m => MonadActive (StateT s m)
instance (Monoid w, MonadActive m) => MonadActive (RWST r w s m)
instance (Monoid w, MonadActive m) => MonadActive (RWST r w s m)
instance (Monoid w, MonadActive m) => MonadActive (WriterT w m)
instance MonadActive m => MonadActive (StateT s m)
instance MonadActive m => MonadActive (ReaderT r m)
instance (Error e, MonadActive m) => MonadActive (ErrorT e m)
instance MonadActive m => MonadActive (MaybeT m)
instance MonadActive m => MonadActive (ListT m)
instance MonadActive m => MonadActive (IdentityT m)
instance MonadActive (ST s)
instance MonadActive (ST s)
instance MonadActive IO
instance MonadActive Identity
instance (MonadIO m, MonadActive m) => MonadActive (ResourceT m)
instance (MonadTrans t, MonadUnsafeIO m, Monad (t m)) => MonadUnsafeIO (t m)
instance MonadUnsafeIO (ST s)
instance MonadUnsafeIO (ST s)
instance MonadUnsafeIO IO
instance (Monoid w, MonadThrow m) => MonadThrow (WriterT w m)
instance MonadThrow m => MonadThrow (StateT s m)
instance (Monoid w, MonadThrow m) => MonadThrow (RWST r w s m)
instance (Monoid w, MonadThrow m) => MonadThrow (RWST r w s m)
instance (Monoid w, MonadThrow m) => MonadThrow (WriterT w m)
instance MonadThrow m => MonadThrow (StateT s m)
instance MonadThrow m => MonadThrow (ResourceT m)
instance MonadThrow m => MonadThrow (ContT r m)
instance MonadThrow m => MonadThrow (ReaderT r m)
instance (Error e, MonadThrow m) => MonadThrow (ErrorT e m)
instance MonadThrow m => MonadThrow (MaybeT m)
instance MonadThrow m => MonadThrow (ListT m)
instance MonadThrow m => MonadThrow (IdentityT m)
instance MonadThrow []
instance MonadThrow (Either SomeException)
instance MonadThrow Maybe
instance MonadThrow IO
instance MonadWriter w m => MonadWriter w (ExceptionT m)
instance MonadState s m => MonadState s (ExceptionT m)
instance MonadReader r m => MonadReader r (ExceptionT m)
instance MonadRWS r w s m => MonadRWS r w s (ExceptionT m)
instance MonadError e m => MonadError e (ExceptionT m)
instance MonadCont m => MonadCont (ExceptionT m)
instance MonadBaseControl b m => MonadBaseControl b (ExceptionT m)
instance MonadTransControl ExceptionT
instance MonadTrans ExceptionT
instance MonadBase b m => MonadBase b (ExceptionT m)
instance Monad m => Monad (ExceptionT m)
instance Monad m => Applicative (ExceptionT m)
instance Monad m => Functor (ExceptionT m)
instance MonadIO m => MonadIO (ExceptionT m)
instance MonadResource m => MonadResource (ExceptionT m)
instance Monad m => MonadThrow (ExceptionT m)
instance MonadBaseControl b m => MonadBaseControl b (ResourceT m)
instance MonadTransControl ResourceT
instance MonadBase b m => MonadBase b (ResourceT m)
instance MonadIO m => MonadIO (ResourceT m)
instance MonadTrans ResourceT
instance Monad m => Monad (ResourceT m)
instance Applicative m => Applicative (ResourceT m)
instance Functor m => Functor (ResourceT m)
instance MMonad ResourceT
instance MFunctor ResourceT
instance Exception InvalidAccess
instance Show InvalidAccess
instance (Monoid w, MonadResource m) => MonadResource (WriterT w m)
instance MonadResource m => MonadResource (StateT s m)
instance (Monoid w, MonadResource m) => MonadResource (RWST r w s m)
instance (Monoid w, MonadResource m) => MonadResource (RWST r w s m)
instance (Monoid w, MonadResource m) => MonadResource (WriterT w m)
instance MonadResource m => MonadResource (StateT s m)
instance MonadResource m => MonadResource (ContT r m)
instance MonadResource m => MonadResource (ReaderT r m)
instance (Error e, MonadResource m) => MonadResource (ErrorT e m)
instance MonadResource m => MonadResource (MaybeT m)
instance MonadResource m => MonadResource (ListT m)
instance MonadResource m => MonadResource (IdentityT m)
instance (MonadThrow m, MonadUnsafeIO m, MonadIO m, Applicative m) => MonadResource (ResourceT m)
instance MonadWriter w m => MonadWriter w (ResourceT m)
instance MonadState s m => MonadState s (ResourceT m)
instance MonadReader r m => MonadReader r (ResourceT m)
instance MonadRWS r w s m => MonadRWS r w s (ResourceT m)
instance MonadError e m => MonadError e (ResourceT m)
instance MonadCont m => MonadCont (ResourceT m)
instance Typeable1 m => Typeable1 (ResourceT m)