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


-- | Revamped effect system
--   
--   Revamped effect system
@package fx
@version 0.4

module Fx

-- | Effectful computation with explicit errors in the context of provided
--   environment.
--   
--   Calling <a>fail</a> causes the whole app to interrupt outputting a
--   message to console. <a>fail</a> is intended to be used in events which
--   you expect never to happen, and hence which should be considered bugs.
--   It is similar to calling <a>fail</a> on IO, with a major difference of
--   the error never getting lost in a concurrent environment.
--   
--   Calling <a>fail</a> results in <a>ErrorCallFxExceptionReason</a> in
--   the triggerred <a>FxException</a>. Thus in effect it is the same as
--   calling the <a>error</a> function.
data Fx env err res

-- | Execute Fx in the scope of a provided environment.
provideAndUse :: Provider err env -> Fx env err res -> Fx env' err res

-- | Collapse an env handler into an environmental effect.
--   
--   <b>Warning:</b> This function leaks the abstraction over the
--   environment. It is your responsibility to ensure that you don't use it
--   to return the environment and use it outside of the handler's scope.
handleEnv :: (env -> Fx env err res) -> Fx env err res

-- | Spawn a thread and start running an effect on it, returning the
--   associated future.
--   
--   Fatal errors on the spawned thread are guaranteed to get propagated to
--   the top. By fatal errors we mean calls to <a>error</a>, <a>fail</a>
--   and uncaught exceptions.
--   
--   Normal errors (the explicit <tt>err</tt> parameter) will only
--   propagate if you use <a>wait</a> at some point.
--   
--   <b>Warning:</b> It is your responsibility to ensure that the whole
--   future executes before the running <a>Fx</a> finishes. Otherwise you
--   will lose the environment in scope of which the future executes. To
--   achieve that use <a>wait</a>.
start :: Fx env err res -> Fx env err' (Future err res)

-- | Block until the future completes either with a result or an error.
wait :: Future err res -> Fx env err res

-- | Execute concurrent effects.
concurrently :: Conc env err res -> Fx env err res

-- | Turn a non-failing IO action into an effect.
--   
--   <b>Warning:</b> It is your responsibility to ensure that it does not
--   throw exceptions!
runTotalIO :: IO res -> Fx env err res

-- | Run IO which produces either an error or result.
--   
--   <b>Warning:</b> It is your responsibility to ensure that it does not
--   throw exceptions!
runPartialIO :: IO (Either err res) -> Fx env err res

-- | Run IO which only throws a specific type of exception.
--   
--   <b>Warning:</b> It is your responsibility to ensure that it doesn't
--   throw any other exceptions!
runExceptionalIO :: Exception exc => IO res -> Fx env exc res

-- | Run STM, crashing in case of STM exceptions.
--   
--   Same as <tt><a>runTotalIO</a> . <a>atomically</a></tt>.
runSTM :: STM res -> Fx env err res

-- | Effectful computation with explicit errors, which encompasses
--   environment acquisition and releasing.
--   
--   Composes well, allowing you to merge multiple providers into one.
--   
--   Builds up on ideas expressed in
--   <a>http://www.haskellforall.com/2013/06/the-resource-applicative.html</a>
--   and later released as the "managed" package.
data Provider err env

-- | Create a resource provider from acquiring and releasing effects.
acquireAndRelease :: Fx () err env -> (env -> Fx () err ()) -> Provider err env

-- | Convert a single resource provider into a pool provider.
--   
--   The wrapper provider acquires the specified amount of resources using
--   the original provider, and returns a modified version of the original
--   provider, whose acquisition and releasing merely takes one resource
--   out of the pool and puts it back when done. No actual acquisition or
--   releasing happens in the wrapped provider. No errors get raised in it
--   either.
--   
--   Use this when you need to access a resource concurrently.
pool :: Int -> Provider err env -> Provider err (Provider err' env)

-- | Handle to a result of an action which may still be being executed on
--   another thread.
--   
--   The way you deal with it is thru the <a>start</a> and <a>wait</a>
--   functions.
data Future err res

-- | Wrapper over <a>Fx</a>, whose instances compose by running
--   computations on separate threads.
--   
--   You can turn <a>Fx</a> into <a>Conc</a> using <a>runFx</a>.
data Conc env err res

-- | Support for running of <a>Fx</a>.
--   
--   Apart from other things this is your interface to turn <a>Fx</a> into
--   <a>IO</a> or <a>Conc</a>.
class FxRunning env err m | m -> env, m -> err
runFx :: FxRunning env err m => Fx env err res -> m res

-- | Support for error handling.
--   
--   Functions provided by this class are particularly helpful, when you
--   need to map into error of type <a>Void</a>.
class ErrHandling m

-- | Interrupt the current computation raising an error.
throwErr :: ErrHandling m => err -> m err res

-- | Handle error in another failing action. Sort of like a bind operation
--   over the error type parameter.
handleErr :: ErrHandling m => (a -> m b res) -> m a res -> m b res

-- | Expose the error in result, producing an action, which is compatible
--   with any error type.
exposeErr :: (ErrHandling m, Functor (m a), Applicative (m b)) => m a res -> m b (Either a res)

-- | Map from error to result, leaving the error be anything.
absorbErr :: (ErrHandling m, Applicative (m b)) => (a -> res) -> m a res -> m b res

-- | Support for mapping of the environment.
class EnvMapping m

-- | Map the environment. Please notice that the expected function is
--   contravariant.
mapEnv :: EnvMapping m => (b -> a) -> m a err res -> m b err res

-- | Fatal failure of an <a>Fx</a> application. Informs of an unrecoverable
--   condition that the application has reached. It is not meant to be
--   caught, because it implies that there is either a bug in your code or
--   a bug in the "fx" library itself, which needs reporting.
--   
--   Consists of a list of thread identifiers specifying the nesting path
--   of the faulty thread and the reason of failure.
data FxException
FxException :: [ThreadId] -> FxExceptionReason -> FxException

-- | Reason of a fatal failure of an <a>Fx</a> application.
data FxExceptionReason
UncaughtExceptionFxExceptionReason :: SomeException -> FxExceptionReason
ErrorCallFxExceptionReason :: ErrorCall -> FxExceptionReason
BugFxExceptionReason :: String -> FxExceptionReason
instance GHC.Base.Applicative (Fx.Future err)
instance GHC.Base.Functor (Fx.Future err)
instance GHC.Base.Functor (Fx.Fx env err)
instance GHC.Base.Applicative (Fx.Fx env err)
instance Control.Selective.Selective (Fx.Fx env err)
instance GHC.Base.Monoid err => GHC.Base.Alternative (Fx.Fx env err)
instance GHC.Base.Monad (Fx.Fx env err)
instance GHC.Base.Monoid err => GHC.Base.MonadPlus (Fx.Fx env err)
instance Control.Selective.Selective (Fx.Future err)
instance GHC.Base.Functor (Fx.Conc env err)
instance Data.Bifunctor.Bifunctor (Fx.Conc env)
instance Fx.ErrHandling (Fx.Conc env)
instance Fx.EnvMapping Fx.Conc
instance GHC.Base.Applicative (Fx.Conc env err)
instance Control.Selective.Selective (Fx.Conc env err)
instance Fx.FxRunning env err (Fx.Conc env err)
instance GHC.Base.Functor (Fx.Provider err)
instance GHC.Base.Applicative (Fx.Provider err)
instance GHC.Base.Monad (Fx.Provider err)
instance Control.Monad.IO.Class.MonadIO (Fx.Provider GHC.Exception.Type.SomeException)
instance Data.Bifunctor.Bifunctor Fx.Provider
instance Fx.FxRunning () err (Fx.Provider err)
instance Fx.FxRunning () Data.Void.Void GHC.Types.IO
instance Fx.FxRunning () err (Control.Monad.Trans.Except.ExceptT err GHC.Types.IO)
instance Fx.FxRunning env err (Control.Monad.Trans.Reader.ReaderT env (Control.Monad.Trans.Except.ExceptT err GHC.Types.IO))
instance Fx.FxRunning () Data.Void.Void (Fx.Fx env err)
instance Control.Monad.Fail.MonadFail (Fx.Fx env err)
instance Control.Monad.IO.Class.MonadIO (Fx.Fx env GHC.Exception.Type.SomeException)
instance Data.Bifunctor.Bifunctor (Fx.Fx env)
instance Fx.ErrHandling (Fx.Fx env)
instance Fx.EnvMapping Fx.Fx
instance GHC.Show.Show Fx.FxException
instance GHC.Exception.Type.Exception Fx.FxException
instance GHC.Show.Show Fx.FxExceptionReason
instance Fx.ErrHandling Fx.Future
instance Data.Bifunctor.Bifunctor Fx.Future