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


-- | An easy to use, performant extensible effects library.
--   
--   An easy to use, performant extensible effects library with seamless
--   integration with the existing Haskell ecosystem.
--   
--   This library provides core definitions with a minimal dependency
--   footprint. See the <tt><a>effectful</a></tt> package for the
--   "batteries-included" variant.
@package effectful-core
@version 2.2.2.2


-- | Type-safe indexing for <a>Env</a>.
--   
--   This module is intended for internal use only, and may change without
--   warning in subsequent releases.
module Effectful.Internal.Effect

-- | The kind of effects.
type Effect = (Type -> Type) -> Type -> Type

-- | A constraint that requires that a particular effect <tt>e</tt> is a
--   member of the type-level list <tt>es</tt>. This is used to
--   parameterize an <a>Eff</a> computation over an arbitrary list of
--   effects, so long as <tt>e</tt> is <i>somewhere</i> in the list.
--   
--   For example, a computation that only needs access to a mutable value
--   of type <a>Integer</a> would have the following type:
--   
--   <pre>
--   <a>State</a> <a>Integer</a> <a>:&gt;</a> es =&gt; <a>Eff</a> es ()
--   </pre>
class (e :: Effect) :> (es :: [Effect])

-- | Get the position of <tt>e</tt> in <tt>es</tt>.
--   
--   <i>Note:</i> GHC is kind enough to cache these values as they're top
--   level CAFs, so the lookup is amortized <tt>O(1)</tt> without any
--   language level tricks.
reifyIndex :: (:>) e es => Int

-- | Convenience operator for expressing that a function uses multiple
--   effects in a more concise way than enumerating them all with
--   <a>(:&gt;)</a>.
--   
--   <pre>
--   [E1, E2, ..., En] <a>:&gt;&gt;</a> es ≡ (E1 <a>:&gt;</a> es, E2 <a>:&gt;</a> es, ..., En :&gt; es)
--   </pre>

-- | <i>Deprecated: Usage of (:&gt;&gt;) slows down GHC too much, so it
--   will be removed in 3.0.0.0. See
--   <a>https://github.com/haskell-effectful/effectful/issues/52#issuecomment-1269155485</a>
--   for more information.</i>
type family xs :>> es :: Constraint

-- | Provide evidence that <tt>xs</tt> is a subset of <tt>es</tt>.
class KnownPrefix es => Subset (xs :: [Effect]) (es :: [Effect])
subsetFullyKnown :: Subset xs es => Bool
reifyIndices :: Subset xs es => [Int]

-- | Calculate length of a statically known prefix of <tt>es</tt>.
class KnownPrefix (es :: [Effect])
prefixLength :: KnownPrefix es => Int

-- | Require that <tt>xs</tt> is the unknown suffix of <tt>es</tt>.
class (xs :: [Effect]) `IsUnknownSuffixOf` (es :: [Effect])

-- | The kind of types with lifted values. For example <tt>Int ::
--   Type</tt>.
type Type = TYPE LiftedRep
instance (Effectful.Internal.Effect.KnownPrefix es, Effectful.Internal.Effect.IsUnknownSuffixOf xs es) => Effectful.Internal.Effect.Subset xs es
instance (xs GHC.Types.~ es) => Effectful.Internal.Effect.IsUnknownSuffixOf xs es
instance Effectful.Internal.Effect.IsUnknownSuffixOf xs es => Effectful.Internal.Effect.IsUnknownSuffixOf xs (e : es)
instance Effectful.Internal.Effect.KnownPrefix es => Effectful.Internal.Effect.Subset '[] es
instance (e Effectful.Internal.Effect.:> es, Effectful.Internal.Effect.Subset xs es) => Effectful.Internal.Effect.Subset (e : xs) es
instance Effectful.Internal.Effect.KnownPrefix es => Effectful.Internal.Effect.KnownPrefix (e : es)
instance Effectful.Internal.Effect.KnownPrefix es
instance (TypeError ...) => e Effectful.Internal.Effect.:> '[]
instance e Effectful.Internal.Effect.:> (e : es)
instance (e Effectful.Internal.Effect.:> es) => e Effectful.Internal.Effect.:> (x : es)

module Effectful.Internal.Utils

-- | Version of bracket with an INLINE pragma to work around
--   <a>https://gitlab.haskell.org/ghc/ghc/-/issues/22824</a>.
inlineBracket :: IO a -> (a -> IO b) -> (a -> IO c) -> IO c

-- | Get an id of a thread that doesn't prevent its garbage collection.
weakThreadId :: ThreadId -> Int
eqThreadId :: ThreadId -> ThreadId -> Bool

-- | The type constructor <a>Any</a> is type to which you can unsafely
--   coerce any lifted type, and back. More concretely, for a lifted type
--   <tt>t</tt> and value <tt>x :: t</tt>, -- <tt>unsafeCoerce
--   (unsafeCoerce x :: Any) :: t</tt> is equivalent to <tt>x</tt>.
type family Any :: k
toAny :: a -> Any
fromAny :: Any -> a

-- | A strict variant of <a>IORef</a>.
data IORef' a
newIORef' :: a -> IO (IORef' a)
readIORef' :: IORef' a -> IO a
writeIORef' :: IORef' a -> a -> IO ()

-- | A strict variant of <a>MVar</a>.
data MVar' a
toMVar' :: MVar a -> IO (MVar' a)
newMVar' :: a -> IO (MVar' a)
readMVar' :: MVar' a -> IO a
modifyMVar' :: MVar' a -> (a -> IO (a, r)) -> IO r
modifyMVar_' :: MVar' a -> (a -> IO a) -> IO ()
instance GHC.Classes.Eq (Effectful.Internal.Utils.IORef' a)
instance GHC.Classes.Eq (Effectful.Internal.Utils.MVar' a)

module Effectful.Internal.Env

-- | A strict (WHNF), <b>thread local</b>, mutable, extensible record
--   indexed by types of kind <a>Effect</a>.
--   
--   <b>Warning: the environment is a mutable data structure and cannot be
--   simultaneously used from multiple threads under any circumstances.</b>
--   
--   In order to pass it to a different thread, you need to perform a deep
--   copy with the <a>cloneEnv</a> funtion.
--   
--   Offers very good performance characteristics for most often performed
--   operations:
--   
--   <ul>
--   <li>Extending: <i><tt>O(n)</tt></i>, where <tt>n</tt> is the size of
--   the effect stack.</li>
--   <li>Shrinking: <i><tt>O(1)</tt></i>.</li>
--   <li>Indexing via <a>(:&gt;)</a>: <i><tt>O(1)</tt></i></li>
--   <li>Modification of a specific element: <i><tt>O(1)</tt></i>.</li>
--   <li>Getting a tail: <i><tt>O(1)</tt></i>.</li>
--   <li>Cloning: <i><tt>O(N)</tt></i>, where <tt>N</tt> is the size of the
--   <a>Storage</a>.</li>
--   </ul>
data Env (es :: [Effect])
Env :: !Int -> !PrimArray Int -> !IORef' Storage -> Env (es :: [Effect])
[envOffset] :: Env (es :: [Effect]) -> !Int
[envRefs] :: Env (es :: [Effect]) -> !PrimArray Int
[envStorage] :: Env (es :: [Effect]) -> !IORef' Storage

-- | A storage of effects.
data Storage
Storage :: !Int -> !Int -> !MutablePrimArray RealWorld Int -> !SmallMutableArray RealWorld Any -> !SmallMutableArray RealWorld Any -> Storage
[stSize] :: Storage -> !Int
[stVersion] :: Storage -> !Int
[stVersions] :: Storage -> !MutablePrimArray RealWorld Int
[stEffects] :: Storage -> !SmallMutableArray RealWorld Any
[stRelinkers] :: Storage -> !SmallMutableArray RealWorld Any

-- | A function for relinking <a>Env</a> objects stored in the handlers
--   and/or making a deep copy of the representation of the effect when
--   cloning the environment.
newtype Relinker :: (Effect -> Type) -> Effect -> Type
[Relinker] :: ((forall es. Env es -> IO (Env es)) -> rep e -> IO (rep e)) -> Relinker rep e

-- | A dummy <a>Relinker</a>.
dummyRelinker :: Relinker rep e

-- | A type of dispatch. For more information consult the documentation in
--   <a>Effectful.Dispatch.Dynamic</a> and
--   <a>Effectful.Dispatch.Static</a>.
data Dispatch
Dynamic :: Dispatch
Static :: SideEffects -> Dispatch

-- | Signifies whether core operations of a statically dispatched effect
--   perform side effects. If an effect is marked as such, the
--   <a>runStaticRep</a> family of functions will require the <a>IOE</a>
--   effect to be in context via the <a>MaybeIOE</a> type family.
data SideEffects
NoSideEffects :: SideEffects
WithSideEffects :: SideEffects

-- | Dispatch types of effects.
type family DispatchOf (e :: Effect) :: Dispatch

-- | Internal representations of effects.
type family EffectRep (d :: Dispatch) :: Effect -> Type

-- | Create an empty environment.
emptyEnv :: IO (Env '[])

-- | Clone the environment to use it in a different thread.
cloneEnv :: Env es -> IO (Env es)

-- | Restore the environment from its clone.
restoreEnv :: Env es -> Env es -> IO ()

-- | Get the current size of the environment.
sizeEnv :: Env es -> IO Int

-- | Access the tail of the environment.
tailEnv :: Env (e : es) -> IO (Env es)

-- | Extend the environment with a new data type.
consEnv :: EffectRep (DispatchOf e) e -> Relinker (EffectRep (DispatchOf e)) e -> Env es -> IO (Env (e : es))

-- | Shrink the environment by one data type.
--   
--   <i>Note:</i> after calling this function <tt>e</tt> from the input
--   environment is no longer usable.
unconsEnv :: Env (e : es) -> IO ()

-- | Replace a specific effect in the stack with a new value.
--   
--   <i>Note:</i> unlike in <a>putEnv</a> the value in not changed in
--   place, so only the new environment will see it.
replaceEnv :: forall e es. e :> es => EffectRep (DispatchOf e) e -> Relinker (EffectRep (DispatchOf e)) e -> Env es -> IO (Env es)

-- | Remove a reference to the replaced effect.
--   
--   <i>Note:</i> after calling this function the input environment is no
--   longer usable.
unreplaceEnv :: forall e es. e :> es => Env es -> IO ()

-- | Reference an existing effect from the top of the stack.
subsumeEnv :: forall e es. e :> es => Env es -> IO (Env (e : es))

-- | Construct an environment containing a permutation (with possible
--   duplicates) of a subset of effects from the input environment.
injectEnv :: forall xs es. Subset xs es => Env es -> IO (Env xs)

-- | Extract a specific data type from the environment.
getEnv :: forall e es. e :> es => Env es -> IO (EffectRep (DispatchOf e) e)

-- | Replace the data type in the environment with a new value (in place).
putEnv :: forall e es. e :> es => Env es -> EffectRep (DispatchOf e) e -> IO ()

-- | Modify the data type in the environment and return a value (in place).
stateEnv :: forall e es a. e :> es => Env es -> (EffectRep (DispatchOf e) e -> IO (a, EffectRep (DispatchOf e) e)) -> IO a

-- | Modify the data type in the environment (in place).
modifyEnv :: forall e es. e :> es => Env es -> (EffectRep (DispatchOf e) e -> IO (EffectRep (DispatchOf e) e)) -> IO ()


-- | Implementation of sequential and concurrent unlifts.
--   
--   This module is intended for internal use only, and may change without
--   warning in subsequent releases.
module Effectful.Internal.Unlift

-- | The strategy to use when unlifting <a>Eff</a> computations via
--   <a>withEffToIO</a>, <a>withRunInIO</a> or the <a>localUnlift</a>
--   family.
data UnliftStrategy

-- | The fastest strategy and a default setting for <a>IOE</a>. An attempt
--   to call the unlifting function in threads distinct from its creator
--   will result in a runtime error.
SeqUnlift :: UnliftStrategy

-- | A strategy that makes it possible for the unlifting function to be
--   called in threads distinct from its creator. See <a>Persistence</a>
--   and <a>Limit</a> settings for more information.
ConcUnlift :: !Persistence -> !Limit -> UnliftStrategy

-- | Persistence setting for the <a>ConcUnlift</a> strategy.
--   
--   Different functions require different persistence strategies.
--   Examples:
--   
--   <ul>
--   <li>Lifting <tt>pooledMapConcurrentlyN</tt> from the <tt>unliftio</tt>
--   library requires the <a>Ephemeral</a> strategy as we don't want jobs
--   to share environment changes made by previous jobs run in the same
--   worker thread.</li>
--   <li>Lifting <a>forkIOWithUnmask</a> requires the <a>Persistent</a>
--   strategy, otherwise the unmasking function would start with a fresh
--   environment each time it's called.</li>
--   </ul>
data Persistence

-- | Don't persist the environment between calls to the unlifting function
--   in threads distinct from its creator.
Ephemeral :: Persistence

-- | Persist the environment between calls to the unlifting function within
--   a particular thread.
Persistent :: Persistence

-- | Limit setting for the <a>ConcUnlift</a> strategy.
data Limit

-- | Behavior dependent on the <a>Persistence</a> setting.
--   
--   For <a>Ephemeral</a>, it limits the amount of uses of the unlifting
--   function in threads distinct from its creator to <tt>N</tt>. The
--   unlifting function will create <tt>N</tt> copies of the environment
--   when called <tt>N</tt> times and <tt>K+1</tt> copies when called <tt>K
--   &lt; N</tt> times.
--   
--   For <a>Persistent</a>, it limits the amount of threads, distinct from
--   the creator of the unlifting function, it can be called in to
--   <tt>N</tt>. The amount of calls to the unlifting function within a
--   particular threads is unlimited. The unlifting function will create
--   <tt>N</tt> copies of the environment when called in <tt>N</tt> threads
--   and <tt>K+1</tt> copies when called in <tt>K &lt; N</tt> threads.
Limited :: !Int -> Limit

-- | Unlimited use of the unlifting function.
Unlimited :: Limit

-- | Sequential unlift.
seqUnlift :: HasCallStack => ((forall r. m r -> IO r) -> IO a) -> Env es -> (forall r. m r -> Env es -> IO r) -> IO a

-- | Concurrent unlift for various strategies and limits.
concUnlift :: HasCallStack => Persistence -> Limit -> ((forall r. m r -> IO r) -> IO a) -> Env es -> (forall r. m r -> Env es -> IO r) -> IO a

-- | Concurrent unlift that doesn't preserve the environment between calls
--   to the unlifting function in threads other than its creator.
ephemeralConcUnlift :: HasCallStack => Int -> ((forall r. m r -> IO r) -> IO a) -> Env es -> (forall r. m r -> Env es -> IO r) -> IO a

-- | Concurrent unlift that preserves the environment between calls to the
--   unlifting function within a particular thread.
persistentConcUnlift :: HasCallStack => Bool -> Int -> ((forall r. m r -> IO r) -> IO a) -> Env es -> (forall r. m r -> Env es -> IO r) -> IO a
instance GHC.Show.Show Effectful.Internal.Unlift.Persistence
instance GHC.Classes.Ord Effectful.Internal.Unlift.Persistence
instance GHC.Generics.Generic Effectful.Internal.Unlift.Persistence
instance GHC.Classes.Eq Effectful.Internal.Unlift.Persistence
instance GHC.Show.Show Effectful.Internal.Unlift.Limit
instance GHC.Classes.Ord Effectful.Internal.Unlift.Limit
instance GHC.Generics.Generic Effectful.Internal.Unlift.Limit
instance GHC.Classes.Eq Effectful.Internal.Unlift.Limit
instance GHC.Show.Show Effectful.Internal.Unlift.UnliftStrategy
instance GHC.Classes.Ord Effectful.Internal.Unlift.UnliftStrategy
instance GHC.Generics.Generic Effectful.Internal.Unlift.UnliftStrategy
instance GHC.Classes.Eq Effectful.Internal.Unlift.UnliftStrategy
instance GHC.Classes.Eq Effectful.Internal.Unlift.EntryId


-- | The <a>Eff</a> monad.
--   
--   This module is intended for internal use only, and may change without
--   warning in subsequent releases.
module Effectful.Internal.Monad

-- | The <a>Eff</a> monad provides the implementation of a computation that
--   performs an arbitrary set of effects. In <tt><a>Eff</a> es a</tt>,
--   <tt>es</tt> is a type-level list that contains all the effects that
--   the computation may perform. For example, a computation that produces
--   an <a>Integer</a> by consuming a <a>String</a> from the global
--   environment and acting upon a single mutable value of type <a>Bool</a>
--   would have the following type:
--   
--   <pre>
--   (<a>Reader</a> <a>String</a> <a>:&gt;</a> es, <a>State</a> <a>Bool</a> <a>:&gt;</a> es) =&gt; <a>Eff</a> es <a>Integer</a>
--   </pre>
--   
--   Abstracting over the list of effects with <a>(:&gt;)</a>:
--   
--   <ul>
--   <li>Allows the computation to be used in functions that may perform
--   other effects.</li>
--   <li>Allows the effects to be handled in any order.</li>
--   </ul>
data Eff (es :: [Effect]) a

-- | Run a pure <a>Eff</a> computation.
--   
--   For running computations with side effects see <a>runEff</a>.
runPureEff :: Eff '[] a -> a

-- | Peel off the constructor of <a>Eff</a>.
unEff :: Eff es a -> Env es -> IO a

-- | Access the underlying <a>IO</a> monad along with the environment.
--   
--   This function is <b>unsafe</b> because it can be used to introduce
--   arbitrary <a>IO</a> actions into pure <a>Eff</a> computations.
unsafeEff :: (Env es -> IO a) -> Eff es a

-- | Access the underlying <a>IO</a> monad.
--   
--   This function is <b>unsafe</b> because it can be used to introduce
--   arbitrary <a>IO</a> actions into pure <a>Eff</a> computations.
unsafeEff_ :: IO a -> Eff es a

-- | Provide the ability to use the <a>Alternative</a> and <a>MonadPlus</a>
--   instance of <a>Eff</a>.
data NonDet :: Effect
[Empty] :: NonDet m a
[:<|>:] :: m a -> m a -> NonDet m a

-- | Provide the ability to use the <a>MonadFail</a> instance of
--   <a>Eff</a>.
data Fail :: Effect
[Fail] :: String -> Fail m a

-- | Run arbitrary <a>IO</a> computations via <a>MonadIO</a> or
--   <a>MonadUnliftIO</a>.
--   
--   <i>Note:</i> it is not recommended to use this effect in application
--   code as it is too liberal. Ideally, this is only used in handlers of
--   more fine-grained effects.
data IOE :: Effect

-- | Run an <a>Eff</a> computation with side effects.
--   
--   For running pure computations see <a>runPureEff</a>.
runEff :: Eff '[IOE] a -> IO a

-- | Provide the ability to perform primitive state-transformer actions.
data Prim :: Effect

-- | <a>PrimState</a> token for <a>Eff</a>. Used instead of
--   <a>RealWorld</a> to prevent the <a>Prim</a> effect from executing
--   arbitrary <a>IO</a> actions via <a>ioToPrim</a>.
data PrimStateEff

-- | Run an <a>Eff</a> computation with primitive state-transformer
--   actions.
runPrim :: IOE :> es => Eff (Prim : es) a -> Eff es a

-- | Lift an <a>Eff</a> computation into an effect stack with one more
--   effect.
raise :: Eff es a -> Eff (e : es) a

-- | Lift an <a>Eff</a> computation into an effect stack with one more
--   effect and create an unlifting function with the given strategy.
raiseWith :: HasCallStack => UnliftStrategy -> ((forall r. Eff (e : es) r -> Eff es r) -> Eff es a) -> Eff (e : es) a

-- | Eliminate a duplicate effect from the top of the effect stack.
subsume :: e :> es => Eff (e : es) a -> Eff es a

-- | Allow for running an effect stack <tt>xs</tt> within <tt>es</tt> as
--   long as <tt>xs</tt> is a permutation (with possible duplicates) of a
--   subset of <tt>es</tt>.
--   
--   Generalizes <a>raise</a> and <a>subsume</a>.
--   
--   <pre>
--   &gt;&gt;&gt; data E1 :: Effect
--   
--   &gt;&gt;&gt; data E2 :: Effect
--   
--   &gt;&gt;&gt; data E3 :: Effect
--   </pre>
--   
--   It makes it possible to rearrange the effect stack however you like:
--   
--   <pre>
--   &gt;&gt;&gt; :{
--     shuffle :: Eff (E3 : E1 : E2 : es) a -&gt; Eff (E1 : E2 : E3 : es) a
--     shuffle = inject
--   :}
--   </pre>
--   
--   It can also turn a monomorphic effect stack into a polymorphic one:
--   
--   <pre>
--   &gt;&gt;&gt; :{
--     toPoly :: (E1 :&gt; es, E2 :&gt; es, E3 :&gt; es) =&gt; Eff [E1, E2, E3] a -&gt; Eff es a
--     toPoly = inject
--   :}
--   </pre>
--   
--   Moreover, it allows for hiding specific effects from downstream:
--   
--   <pre>
--   &gt;&gt;&gt; :{
--     onlyE1 :: Eff (E1 : es) a -&gt; Eff (E1 : E2 : E3 : es) a
--     onlyE1 = inject
--   :}
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; :{
--     onlyE2 :: Eff (E2 : es) a -&gt; Eff (E1 : E2 : E3 : es) a
--     onlyE2 = inject
--   :}
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; :{
--     onlyE3 :: Eff (E3 : es) a -&gt; Eff (E1 : E2 : E3 : es) a
--     onlyE3 = inject
--   :}
--   </pre>
--   
--   However, it's not possible to inject a computation into an
--   incompatible effect stack:
--   
--   <pre>
--   &gt;&gt;&gt; :{
--     coerceEs :: Eff es1 a -&gt; Eff es2 a
--     coerceEs = inject
--   :}
--   ...
--   ...Couldn't match type ‘es1’ with ‘es2’
--   ...
--   </pre>
inject :: Subset xs es => Eff xs a -> Eff es a

-- | Provide evidence that <tt>xs</tt> is a subset of <tt>es</tt>.
class KnownPrefix es => Subset (xs :: [Effect]) (es :: [Effect])

-- | The strategy to use when unlifting <a>Eff</a> computations via
--   <a>withEffToIO</a>, <a>withRunInIO</a> or the <a>localUnlift</a>
--   family.
data UnliftStrategy

-- | The fastest strategy and a default setting for <a>IOE</a>. An attempt
--   to call the unlifting function in threads distinct from its creator
--   will result in a runtime error.
SeqUnlift :: UnliftStrategy

-- | A strategy that makes it possible for the unlifting function to be
--   called in threads distinct from its creator. See <a>Persistence</a>
--   and <a>Limit</a> settings for more information.
ConcUnlift :: !Persistence -> !Limit -> UnliftStrategy

-- | Persistence setting for the <a>ConcUnlift</a> strategy.
--   
--   Different functions require different persistence strategies.
--   Examples:
--   
--   <ul>
--   <li>Lifting <tt>pooledMapConcurrentlyN</tt> from the <tt>unliftio</tt>
--   library requires the <a>Ephemeral</a> strategy as we don't want jobs
--   to share environment changes made by previous jobs run in the same
--   worker thread.</li>
--   <li>Lifting <a>forkIOWithUnmask</a> requires the <a>Persistent</a>
--   strategy, otherwise the unmasking function would start with a fresh
--   environment each time it's called.</li>
--   </ul>
data Persistence

-- | Don't persist the environment between calls to the unlifting function
--   in threads distinct from its creator.
Ephemeral :: Persistence

-- | Persist the environment between calls to the unlifting function within
--   a particular thread.
Persistent :: Persistence

-- | Limit setting for the <a>ConcUnlift</a> strategy.
data Limit

-- | Behavior dependent on the <a>Persistence</a> setting.
--   
--   For <a>Ephemeral</a>, it limits the amount of uses of the unlifting
--   function in threads distinct from its creator to <tt>N</tt>. The
--   unlifting function will create <tt>N</tt> copies of the environment
--   when called <tt>N</tt> times and <tt>K+1</tt> copies when called <tt>K
--   &lt; N</tt> times.
--   
--   For <a>Persistent</a>, it limits the amount of threads, distinct from
--   the creator of the unlifting function, it can be called in to
--   <tt>N</tt>. The amount of calls to the unlifting function within a
--   particular threads is unlimited. The unlifting function will create
--   <tt>N</tt> copies of the environment when called in <tt>N</tt> threads
--   and <tt>K+1</tt> copies when called in <tt>K &lt; N</tt> threads.
Limited :: !Int -> Limit

-- | Unlimited use of the unlifting function.
Unlimited :: Limit

-- | Get the current <a>UnliftStrategy</a>.
unliftStrategy :: IOE :> es => Eff es UnliftStrategy

-- | Locally override the <a>UnliftStrategy</a> with the given value.
withUnliftStrategy :: IOE :> es => UnliftStrategy -> Eff es a -> Eff es a

-- | Create an unlifting function with the current <a>UnliftStrategy</a>.
--   
--   This function is equivalent to <a>withRunInIO</a>, but has a
--   <a>HasCallStack</a> constraint for accurate stack traces in case an
--   insufficiently powerful <a>UnliftStrategy</a> is used and the
--   unlifting function fails.
withEffToIO :: (HasCallStack, IOE :> es) => ((forall r. Eff es r -> IO r) -> IO a) -> Eff es a

-- | Create an unlifting function with the <a>SeqUnlift</a> strategy.
withSeqEffToIO :: (HasCallStack, IOE :> es) => ((forall r. Eff es r -> IO r) -> IO a) -> Eff es a

-- | Create an unlifting function with the <a>ConcUnlift</a> strategy.
withConcEffToIO :: (HasCallStack, IOE :> es) => Persistence -> Limit -> ((forall r. Eff es r -> IO r) -> IO a) -> Eff es a

-- | Create an unlifting function with the <a>SeqUnlift</a> strategy.
seqUnliftIO :: HasCallStack => Env es -> ((forall r. Eff es r -> IO r) -> IO a) -> IO a

-- | Create an unlifting function with the <a>ConcUnlift</a> strategy.
concUnliftIO :: HasCallStack => Env es -> Persistence -> Limit -> ((forall r. Eff es r -> IO r) -> IO a) -> IO a

-- | Type signature of the effect handler.
type EffectHandler e es = forall a localEs. (HasCallStack, e :> localEs) => LocalEnv localEs es " Capture of the local environment for handling local 'Eff' computations when @e@ is a higher order effect." -> e (Eff localEs) a " The effect performed in the local environment." -> Eff es a

-- | Opaque representation of the <a>Eff</a> environment at the point of
--   calling the <a>send</a> function, i.e. right before the control is
--   passed to the effect handler.
--   
--   The second type variable represents effects of a handler and is needed
--   for technical reasons to guarantee soundness (see <a>SharedSuffix</a>
--   for more information).
newtype LocalEnv (localEs :: [Effect]) (handlerEs :: [Effect])
LocalEnv :: Env localEs -> LocalEnv (localEs :: [Effect]) (handlerEs :: [Effect])

-- | An internal representation of dynamically dispatched effects, i.e. the
--   effect handler bundled with its environment.
data Handler :: Effect -> Type
[Handler] :: !Env handlerEs -> !EffectHandler e handlerEs -> Handler e
relinkHandler :: Relinker Handler e

-- | Run a dynamically dispatched effect with the given handler.
runHandler :: DispatchOf e ~ Dynamic => Handler e -> Eff (e : es) a -> Eff es a

-- | Send an operation of the given effect to its handler for execution.
send :: (HasCallStack, DispatchOf e ~ Dynamic, e :> es) => e (Eff es) a -> Eff es a

-- | Internal representations of statically dispatched effects.
data family StaticRep (e :: Effect) :: Type

-- | Require the <a>IOE</a> effect for running statically dispatched
--   effects whose operations perform side effects.
type family MaybeIOE (sideEffects :: SideEffects) (es :: [Effect]) :: Constraint

-- | Run a statically dispatched effect with the given initial
--   representation and return the final value along with the final
--   representation.
runStaticRep :: (DispatchOf e ~ Static sideEffects, MaybeIOE sideEffects es) => StaticRep e -> Eff (e : es) a -> Eff es (a, StaticRep e)

-- | Run a statically dispatched effect with the given initial
--   representation and return the final value, discarding the final
--   representation.
evalStaticRep :: (DispatchOf e ~ Static sideEffects, MaybeIOE sideEffects es) => StaticRep e -> Eff (e : es) a -> Eff es a

-- | Run a statically dispatched effect with the given initial
--   representation and return the final representation, discarding the
--   final value.
execStaticRep :: (DispatchOf e ~ Static sideEffects, MaybeIOE sideEffects es) => StaticRep e -> Eff (e : es) a -> Eff es (StaticRep e)

-- | Fetch the current representation of the effect.
getStaticRep :: (DispatchOf e ~ Static sideEffects, e :> es) => Eff es (StaticRep e)

-- | Set the current representation of the effect to the given value.
putStaticRep :: (DispatchOf e ~ Static sideEffects, e :> es) => StaticRep e -> Eff es ()

-- | Apply the function to the current representation of the effect and
--   return a value.
stateStaticRep :: (DispatchOf e ~ Static sideEffects, e :> es) => (StaticRep e -> (a, StaticRep e)) -> Eff es a

-- | Apply the monadic function to the current representation of the effect
--   and return a value.
stateStaticRepM :: (DispatchOf e ~ Static sideEffects, e :> es) => (StaticRep e -> Eff es (a, StaticRep e)) -> Eff es a

-- | Execute a computation with a temporarily modified representation of
--   the effect.
localStaticRep :: (DispatchOf e ~ Static sideEffects, e :> es) => (StaticRep e -> StaticRep e) -> Eff es a -> Eff es a

-- | Extend the environment with a new data type.
consEnv :: EffectRep (DispatchOf e) e -> Relinker (EffectRep (DispatchOf e)) e -> Env es -> IO (Env (e : es))

-- | Extract a specific data type from the environment.
getEnv :: forall e es. e :> es => Env es -> IO (EffectRep (DispatchOf e) e)

-- | Replace the data type in the environment with a new value (in place).
putEnv :: forall e es. e :> es => Env es -> EffectRep (DispatchOf e) e -> IO ()

-- | Modify the data type in the environment and return a value (in place).
stateEnv :: forall e es a. e :> es => Env es -> (EffectRep (DispatchOf e) e -> IO (a, EffectRep (DispatchOf e) e)) -> IO a

-- | Modify the data type in the environment (in place).
modifyEnv :: forall e es. e :> es => Env es -> (EffectRep (DispatchOf e) e -> IO (EffectRep (DispatchOf e) e)) -> IO ()
instance GHC.Base.Semigroup a => GHC.Base.Semigroup (Effectful.Internal.Monad.Eff es a)
instance GHC.Base.Monoid a => GHC.Base.Monoid (Effectful.Internal.Monad.Eff es a)
instance (Effectful.Internal.Monad.Prim Effectful.Internal.Effect.:> es) => Control.Monad.Primitive.PrimMonad (Effectful.Internal.Monad.Eff es)
instance (Effectful.Internal.Monad.IOE Effectful.Internal.Effect.:> es) => Control.Monad.IO.Class.MonadIO (Effectful.Internal.Monad.Eff es)
instance (Effectful.Internal.Monad.IOE Effectful.Internal.Effect.:> es) => Control.Monad.IO.Unlift.MonadUnliftIO (Effectful.Internal.Monad.Eff es)
instance (Effectful.Internal.Monad.IOE Effectful.Internal.Effect.:> es) => Control.Monad.Base.MonadBase GHC.Types.IO (Effectful.Internal.Monad.Eff es)
instance (Effectful.Internal.Monad.IOE Effectful.Internal.Effect.:> es) => Control.Monad.Trans.Control.MonadBaseControl GHC.Types.IO (Effectful.Internal.Monad.Eff es)
instance (Effectful.Internal.Monad.Fail Effectful.Internal.Effect.:> es) => Control.Monad.Fail.MonadFail (Effectful.Internal.Monad.Eff es)
instance (Effectful.Internal.Monad.NonDet Effectful.Internal.Effect.:> es) => GHC.Base.Alternative (Effectful.Internal.Monad.Eff es)
instance (Effectful.Internal.Monad.NonDet Effectful.Internal.Effect.:> es) => GHC.Base.MonadPlus (Effectful.Internal.Monad.Eff es)
instance GHC.Base.Functor (Effectful.Internal.Monad.Eff es)
instance GHC.Base.Applicative (Effectful.Internal.Monad.Eff es)
instance GHC.Base.Monad (Effectful.Internal.Monad.Eff es)
instance Control.Monad.Fix.MonadFix (Effectful.Internal.Monad.Eff es)
instance Control.Monad.Catch.MonadThrow (Effectful.Internal.Monad.Eff es)
instance Control.Monad.Catch.MonadCatch (Effectful.Internal.Monad.Eff es)
instance Control.Monad.Catch.MonadMask (Effectful.Internal.Monad.Eff es)


-- | Unsafe utilities for statically dispatched effects.
module Effectful.Dispatch.Static.Unsafe

-- | Utility for lifting <a>IO</a> computations of type
--   
--   <pre>
--   <a>IO</a> a -&gt; <a>IO</a> b
--   </pre>
--   
--   to
--   
--   <pre>
--   <a>Eff</a> es a -&gt; <a>Eff</a> es b
--   </pre>
--   
--   This function is <b>highly unsafe</b> because:
--   
--   <ul>
--   <li>It can be used to introduce arbitrary <a>IO</a> actions into pure
--   <a>Eff</a> computations.</li>
--   <li>The <a>IO</a> computation must not run its argument in a different
--   thread, but it's not checked anywhere.</li>
--   </ul>
--   
--   <b>If you disregard the second point, segmentation faults await.</b>
reallyUnsafeLiftMapIO :: (IO a -> IO b) -> Eff es a -> Eff es b

-- | Create an unlifting function.
--   
--   This function is <b>highly unsafe</b> because:
--   
--   <ul>
--   <li>It can be used to introduce arbitrary <a>IO</a> actions into pure
--   <a>Eff</a> computations.</li>
--   <li>Unlifted <a>Eff</a> computations must not be run in a thread
--   distinct from the caller of <a>reallyUnsafeUnliftIO</a>, but it's not
--   checked anywhere.</li>
--   </ul>
--   
--   <b>If you disregard the second point, segmentation faults await.</b>
reallyUnsafeUnliftIO :: ((forall r. Eff es r -> IO r) -> IO a) -> Eff es a


-- | Primitive API for statically dispatched effects.
--   
--   This module exposes internal implementation details of the <a>Eff</a>
--   monad. Most of the time functions from
--   <a>Effectful.Dispatch.Static</a> are sufficient.
--   
--   <i>Warning:</i> playing the so called "type tetris" with functions
--   from this module is not enough. Their misuse might lead to memory
--   corruption or segmentation faults, so make sure you understand what
--   you're doing.
module Effectful.Dispatch.Static.Primitive

-- | A strict (WHNF), <b>thread local</b>, mutable, extensible record
--   indexed by types of kind <a>Effect</a>.
--   
--   <b>Warning: the environment is a mutable data structure and cannot be
--   simultaneously used from multiple threads under any circumstances.</b>
--   
--   In order to pass it to a different thread, you need to perform a deep
--   copy with the <a>cloneEnv</a> funtion.
--   
--   Offers very good performance characteristics for most often performed
--   operations:
--   
--   <ul>
--   <li>Extending: <i><tt>O(n)</tt></i>, where <tt>n</tt> is the size of
--   the effect stack.</li>
--   <li>Shrinking: <i><tt>O(1)</tt></i>.</li>
--   <li>Indexing via <a>(:&gt;)</a>: <i><tt>O(1)</tt></i></li>
--   <li>Modification of a specific element: <i><tt>O(1)</tt></i>.</li>
--   <li>Getting a tail: <i><tt>O(1)</tt></i>.</li>
--   <li>Cloning: <i><tt>O(N)</tt></i>, where <tt>N</tt> is the size of the
--   <a>Storage</a>.</li>
--   </ul>
data Env (es :: [Effect])

-- | A function for relinking <a>Env</a> objects stored in the handlers
--   and/or making a deep copy of the representation of the effect when
--   cloning the environment.
newtype Relinker :: (Effect -> Type) -> Effect -> Type
[Relinker] :: ((forall es. Env es -> IO (Env es)) -> rep e -> IO (rep e)) -> Relinker rep e

-- | A dummy <a>Relinker</a>.
dummyRelinker :: Relinker rep e

-- | Internal representations of effects.
type family EffectRep (d :: Dispatch) :: Effect -> Type

-- | Extend the environment with a new data type.
consEnv :: EffectRep (DispatchOf e) e -> Relinker (EffectRep (DispatchOf e)) e -> Env es -> IO (Env (e : es))

-- | Shrink the environment by one data type.
--   
--   <i>Note:</i> after calling this function <tt>e</tt> from the input
--   environment is no longer usable.
unconsEnv :: Env (e : es) -> IO ()

-- | Extract a specific data type from the environment.
getEnv :: forall e es. e :> es => Env es -> IO (EffectRep (DispatchOf e) e)

-- | Replace the data type in the environment with a new value (in place).
putEnv :: forall e es. e :> es => Env es -> EffectRep (DispatchOf e) e -> IO ()

-- | Modify the data type in the environment and return a value (in place).
stateEnv :: forall e es a. e :> es => Env es -> (EffectRep (DispatchOf e) e -> IO (a, EffectRep (DispatchOf e) e)) -> IO a

-- | Modify the data type in the environment (in place).
modifyEnv :: forall e es. e :> es => Env es -> (EffectRep (DispatchOf e) e -> IO (EffectRep (DispatchOf e) e)) -> IO ()

-- | Create an empty environment.
emptyEnv :: IO (Env '[])

-- | Clone the environment to use it in a different thread.
cloneEnv :: Env es -> IO (Env es)

-- | Restore the environment from its clone.
restoreEnv :: Env es -> Env es -> IO ()

-- | Get the current size of the environment.
sizeEnv :: Env es -> IO Int

-- | Access the tail of the environment.
tailEnv :: Env (e : es) -> IO (Env es)


-- | Statically dispatched effects.
module Effectful.Dispatch.Static

-- | Internal representations of statically dispatched effects.
data family StaticRep (e :: Effect) :: Type

-- | Signifies whether core operations of a statically dispatched effect
--   perform side effects. If an effect is marked as such, the
--   <a>runStaticRep</a> family of functions will require the <a>IOE</a>
--   effect to be in context via the <a>MaybeIOE</a> type family.
data SideEffects
NoSideEffects :: SideEffects
WithSideEffects :: SideEffects

-- | Require the <a>IOE</a> effect for running statically dispatched
--   effects whose operations perform side effects.
type family MaybeIOE (sideEffects :: SideEffects) (es :: [Effect]) :: Constraint

-- | Run a statically dispatched effect with the given initial
--   representation and return the final value along with the final
--   representation.
runStaticRep :: (DispatchOf e ~ Static sideEffects, MaybeIOE sideEffects es) => StaticRep e -> Eff (e : es) a -> Eff es (a, StaticRep e)

-- | Run a statically dispatched effect with the given initial
--   representation and return the final value, discarding the final
--   representation.
evalStaticRep :: (DispatchOf e ~ Static sideEffects, MaybeIOE sideEffects es) => StaticRep e -> Eff (e : es) a -> Eff es a

-- | Run a statically dispatched effect with the given initial
--   representation and return the final representation, discarding the
--   final value.
execStaticRep :: (DispatchOf e ~ Static sideEffects, MaybeIOE sideEffects es) => StaticRep e -> Eff (e : es) a -> Eff es (StaticRep e)

-- | Fetch the current representation of the effect.
getStaticRep :: (DispatchOf e ~ Static sideEffects, e :> es) => Eff es (StaticRep e)

-- | Set the current representation of the effect to the given value.
putStaticRep :: (DispatchOf e ~ Static sideEffects, e :> es) => StaticRep e -> Eff es ()

-- | Apply the function to the current representation of the effect and
--   return a value.
stateStaticRep :: (DispatchOf e ~ Static sideEffects, e :> es) => (StaticRep e -> (a, StaticRep e)) -> Eff es a

-- | Apply the monadic function to the current representation of the effect
--   and return a value.
stateStaticRepM :: (DispatchOf e ~ Static sideEffects, e :> es) => (StaticRep e -> Eff es (a, StaticRep e)) -> Eff es a

-- | Execute a computation with a temporarily modified representation of
--   the effect.
localStaticRep :: (DispatchOf e ~ Static sideEffects, e :> es) => (StaticRep e -> StaticRep e) -> Eff es a -> Eff es a

-- | Create an unlifting function with the <a>SeqUnlift</a> strategy.
seqUnliftIO :: HasCallStack => Env es -> ((forall r. Eff es r -> IO r) -> IO a) -> IO a

-- | Create an unlifting function with the <a>ConcUnlift</a> strategy.
concUnliftIO :: HasCallStack => Env es -> Persistence -> Limit -> ((forall r. Eff es r -> IO r) -> IO a) -> IO a

-- | Create an unlifting function with the <a>SeqUnlift</a> strategy.
--   
--   This function is <b>unsafe</b> because it can be used to introduce
--   arbitrary <a>IO</a> actions into pure <a>Eff</a> computations.
unsafeSeqUnliftIO :: HasCallStack => ((forall r. Eff es r -> IO r) -> IO a) -> Eff es a

-- | Create an unlifting function with the <a>ConcUnlift</a> strategy.
--   
--   This function is <b>unsafe</b> because it can be used to introduce
--   arbitrary <a>IO</a> actions into pure <a>Eff</a> computations.
unsafeConcUnliftIO :: HasCallStack => Persistence -> Limit -> ((forall r. Eff es r -> IO r) -> IO a) -> Eff es a

-- | Peel off the constructor of <a>Eff</a>.
unEff :: Eff es a -> Env es -> IO a

-- | Access the underlying <a>IO</a> monad along with the environment.
--   
--   This function is <b>unsafe</b> because it can be used to introduce
--   arbitrary <a>IO</a> actions into pure <a>Eff</a> computations.
unsafeEff :: (Env es -> IO a) -> Eff es a

-- | Access the underlying <a>IO</a> monad.
--   
--   This function is <b>unsafe</b> because it can be used to introduce
--   arbitrary <a>IO</a> actions into pure <a>Eff</a> computations.
unsafeEff_ :: IO a -> Eff es a

-- | Utility for lifting <a>IO</a> computations of type
--   
--   <pre>
--   <a>IO</a> a -&gt; <a>IO</a> b
--   </pre>
--   
--   to
--   
--   <pre>
--   <a>Eff</a> es a -&gt; <a>Eff</a> es b
--   </pre>
--   
--   <i>Note:</i> the computation must not run its argument in a separate
--   thread, attempting to do so will result in a runtime error.
--   
--   This function is <b>unsafe</b> because it can be used to introduce
--   arbitrary <a>IO</a> actions into pure <a>Eff</a> computations.
unsafeLiftMapIO :: HasCallStack => (IO a -> IO b) -> Eff es a -> Eff es b

-- | Request a CallStack.
--   
--   NOTE: The implicit parameter <tt>?callStack :: CallStack</tt> is an
--   implementation detail and <b>should not</b> be considered part of the
--   <a>CallStack</a> API, we may decide to change the implementation in
--   the future.
type HasCallStack = ?callStack :: CallStack

module Effectful

-- | The <a>Eff</a> monad provides the implementation of a computation that
--   performs an arbitrary set of effects. In <tt><a>Eff</a> es a</tt>,
--   <tt>es</tt> is a type-level list that contains all the effects that
--   the computation may perform. For example, a computation that produces
--   an <a>Integer</a> by consuming a <a>String</a> from the global
--   environment and acting upon a single mutable value of type <a>Bool</a>
--   would have the following type:
--   
--   <pre>
--   (<a>Reader</a> <a>String</a> <a>:&gt;</a> es, <a>State</a> <a>Bool</a> <a>:&gt;</a> es) =&gt; <a>Eff</a> es <a>Integer</a>
--   </pre>
--   
--   Abstracting over the list of effects with <a>(:&gt;)</a>:
--   
--   <ul>
--   <li>Allows the computation to be used in functions that may perform
--   other effects.</li>
--   <li>Allows the effects to be handled in any order.</li>
--   </ul>
data Eff (es :: [Effect]) a

-- | The kind of effects.
type Effect = (Type -> Type) -> Type -> Type

-- | A type of dispatch. For more information consult the documentation in
--   <a>Effectful.Dispatch.Dynamic</a> and
--   <a>Effectful.Dispatch.Static</a>.
data Dispatch
Dynamic :: Dispatch
Static :: SideEffects -> Dispatch

-- | Dispatch types of effects.
type family DispatchOf (e :: Effect) :: Dispatch

-- | A constraint that requires that a particular effect <tt>e</tt> is a
--   member of the type-level list <tt>es</tt>. This is used to
--   parameterize an <a>Eff</a> computation over an arbitrary list of
--   effects, so long as <tt>e</tt> is <i>somewhere</i> in the list.
--   
--   For example, a computation that only needs access to a mutable value
--   of type <a>Integer</a> would have the following type:
--   
--   <pre>
--   <a>State</a> <a>Integer</a> <a>:&gt;</a> es =&gt; <a>Eff</a> es ()
--   </pre>
class (e :: Effect) :> (es :: [Effect])

-- | Convenience operator for expressing that a function uses multiple
--   effects in a more concise way than enumerating them all with
--   <a>(:&gt;)</a>.
--   
--   <pre>
--   [E1, E2, ..., En] <a>:&gt;&gt;</a> es ≡ (E1 <a>:&gt;</a> es, E2 <a>:&gt;</a> es, ..., En :&gt; es)
--   </pre>

-- | <i>Deprecated: Usage of (:&gt;&gt;) slows down GHC too much, so it
--   will be removed in 3.0.0.0. See
--   <a>https://github.com/haskell-effectful/effectful/issues/52#issuecomment-1269155485</a>
--   for more information.</i>
type family xs :>> es :: Constraint

-- | Run a pure <a>Eff</a> computation.
--   
--   For running computations with side effects see <a>runEff</a>.
runPureEff :: Eff '[] a -> a

-- | Run an <a>Eff</a> computation with side effects.
--   
--   For running pure computations see <a>runPureEff</a>.
runEff :: Eff '[IOE] a -> IO a

-- | Run arbitrary <a>IO</a> computations via <a>MonadIO</a> or
--   <a>MonadUnliftIO</a>.
--   
--   <i>Note:</i> it is not recommended to use this effect in application
--   code as it is too liberal. Ideally, this is only used in handlers of
--   more fine-grained effects.
data IOE :: Effect

-- | The strategy to use when unlifting <a>Eff</a> computations via
--   <a>withEffToIO</a>, <a>withRunInIO</a> or the <a>localUnlift</a>
--   family.
data UnliftStrategy

-- | The fastest strategy and a default setting for <a>IOE</a>. An attempt
--   to call the unlifting function in threads distinct from its creator
--   will result in a runtime error.
SeqUnlift :: UnliftStrategy

-- | A strategy that makes it possible for the unlifting function to be
--   called in threads distinct from its creator. See <a>Persistence</a>
--   and <a>Limit</a> settings for more information.
ConcUnlift :: !Persistence -> !Limit -> UnliftStrategy

-- | Persistence setting for the <a>ConcUnlift</a> strategy.
--   
--   Different functions require different persistence strategies.
--   Examples:
--   
--   <ul>
--   <li>Lifting <tt>pooledMapConcurrentlyN</tt> from the <tt>unliftio</tt>
--   library requires the <a>Ephemeral</a> strategy as we don't want jobs
--   to share environment changes made by previous jobs run in the same
--   worker thread.</li>
--   <li>Lifting <a>forkIOWithUnmask</a> requires the <a>Persistent</a>
--   strategy, otherwise the unmasking function would start with a fresh
--   environment each time it's called.</li>
--   </ul>
data Persistence

-- | Don't persist the environment between calls to the unlifting function
--   in threads distinct from its creator.
Ephemeral :: Persistence

-- | Persist the environment between calls to the unlifting function within
--   a particular thread.
Persistent :: Persistence

-- | Limit setting for the <a>ConcUnlift</a> strategy.
data Limit

-- | Behavior dependent on the <a>Persistence</a> setting.
--   
--   For <a>Ephemeral</a>, it limits the amount of uses of the unlifting
--   function in threads distinct from its creator to <tt>N</tt>. The
--   unlifting function will create <tt>N</tt> copies of the environment
--   when called <tt>N</tt> times and <tt>K+1</tt> copies when called <tt>K
--   &lt; N</tt> times.
--   
--   For <a>Persistent</a>, it limits the amount of threads, distinct from
--   the creator of the unlifting function, it can be called in to
--   <tt>N</tt>. The amount of calls to the unlifting function within a
--   particular threads is unlimited. The unlifting function will create
--   <tt>N</tt> copies of the environment when called in <tt>N</tt> threads
--   and <tt>K+1</tt> copies when called in <tt>K &lt; N</tt> threads.
Limited :: !Int -> Limit

-- | Unlimited use of the unlifting function.
Unlimited :: Limit

-- | Get the current <a>UnliftStrategy</a>.
unliftStrategy :: IOE :> es => Eff es UnliftStrategy

-- | Locally override the <a>UnliftStrategy</a> with the given value.
withUnliftStrategy :: IOE :> es => UnliftStrategy -> Eff es a -> Eff es a

-- | Create an unlifting function with the current <a>UnliftStrategy</a>.
--   
--   This function is equivalent to <a>withRunInIO</a>, but has a
--   <a>HasCallStack</a> constraint for accurate stack traces in case an
--   insufficiently powerful <a>UnliftStrategy</a> is used and the
--   unlifting function fails.
withEffToIO :: (HasCallStack, IOE :> es) => ((forall r. Eff es r -> IO r) -> IO a) -> Eff es a

-- | Create an unlifting function with the <a>SeqUnlift</a> strategy.
withSeqEffToIO :: (HasCallStack, IOE :> es) => ((forall r. Eff es r -> IO r) -> IO a) -> Eff es a

-- | Create an unlifting function with the <a>ConcUnlift</a> strategy.
withConcEffToIO :: (HasCallStack, IOE :> es) => Persistence -> Limit -> ((forall r. Eff es r -> IO r) -> IO a) -> Eff es a

-- | Lift an <a>Eff</a> computation into an effect stack with one more
--   effect.
raise :: Eff es a -> Eff (e : es) a

-- | Lift an <a>Eff</a> computation into an effect stack with one more
--   effect and create an unlifting function with the given strategy.
raiseWith :: HasCallStack => UnliftStrategy -> ((forall r. Eff (e : es) r -> Eff es r) -> Eff es a) -> Eff (e : es) a

-- | Eliminate a duplicate effect from the top of the effect stack.
subsume :: e :> es => Eff (e : es) a -> Eff es a

-- | Allow for running an effect stack <tt>xs</tt> within <tt>es</tt> as
--   long as <tt>xs</tt> is a permutation (with possible duplicates) of a
--   subset of <tt>es</tt>.
--   
--   Generalizes <a>raise</a> and <a>subsume</a>.
--   
--   <pre>
--   &gt;&gt;&gt; data E1 :: Effect
--   
--   &gt;&gt;&gt; data E2 :: Effect
--   
--   &gt;&gt;&gt; data E3 :: Effect
--   </pre>
--   
--   It makes it possible to rearrange the effect stack however you like:
--   
--   <pre>
--   &gt;&gt;&gt; :{
--     shuffle :: Eff (E3 : E1 : E2 : es) a -&gt; Eff (E1 : E2 : E3 : es) a
--     shuffle = inject
--   :}
--   </pre>
--   
--   It can also turn a monomorphic effect stack into a polymorphic one:
--   
--   <pre>
--   &gt;&gt;&gt; :{
--     toPoly :: (E1 :&gt; es, E2 :&gt; es, E3 :&gt; es) =&gt; Eff [E1, E2, E3] a -&gt; Eff es a
--     toPoly = inject
--   :}
--   </pre>
--   
--   Moreover, it allows for hiding specific effects from downstream:
--   
--   <pre>
--   &gt;&gt;&gt; :{
--     onlyE1 :: Eff (E1 : es) a -&gt; Eff (E1 : E2 : E3 : es) a
--     onlyE1 = inject
--   :}
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; :{
--     onlyE2 :: Eff (E2 : es) a -&gt; Eff (E1 : E2 : E3 : es) a
--     onlyE2 = inject
--   :}
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; :{
--     onlyE3 :: Eff (E3 : es) a -&gt; Eff (E1 : E2 : E3 : es) a
--     onlyE3 = inject
--   :}
--   </pre>
--   
--   However, it's not possible to inject a computation into an
--   incompatible effect stack:
--   
--   <pre>
--   &gt;&gt;&gt; :{
--     coerceEs :: Eff es1 a -&gt; Eff es2 a
--     coerceEs = inject
--   :}
--   ...
--   ...Couldn't match type ‘es1’ with ‘es2’
--   ...
--   </pre>
inject :: Subset xs es => Eff xs a -> Eff es a

-- | Provide evidence that <tt>xs</tt> is a subset of <tt>es</tt>.
class KnownPrefix es => Subset (xs :: [Effect]) (es :: [Effect])

-- | Monads in which <a>IO</a> computations may be embedded. Any monad
--   built by applying a sequence of monad transformers to the <a>IO</a>
--   monad will be an instance of this class.
--   
--   Instances should satisfy the following laws, which state that
--   <a>liftIO</a> is a transformer of monads:
--   
--   <ul>
--   <li><pre><a>liftIO</a> . <a>return</a> = <a>return</a></pre></li>
--   <li><pre><a>liftIO</a> (m &gt;&gt;= f) = <a>liftIO</a> m &gt;&gt;=
--   (<a>liftIO</a> . f)</pre></li>
--   </ul>
class Monad m => MonadIO (m :: Type -> Type)

-- | Lift a computation from the <a>IO</a> monad. This allows us to run IO
--   computations in any monadic stack, so long as it supports these kinds
--   of operations (i.e. <a>IO</a> is the base monad for the stack).
--   
--   <h3><b>Example</b></h3>
--   
--   <pre>
--   import Control.Monad.Trans.State -- from the "transformers" library
--   
--   printState :: Show s =&gt; StateT s IO ()
--   printState = do
--     state &lt;- get
--     liftIO $ print state
--   </pre>
--   
--   Had we omitted <tt><a>liftIO</a></tt>, we would have ended up with
--   this error:
--   
--   <pre>
--   • Couldn't match type ‘IO’ with ‘StateT s IO’
--    Expected type: StateT s IO ()
--      Actual type: IO ()
--   </pre>
--   
--   The important part here is the mismatch between <tt>StateT s IO
--   ()</tt> and <tt><a>IO</a> ()</tt>.
--   
--   Luckily, we know of a function that takes an <tt><a>IO</a> a</tt> and
--   returns an <tt>(m a)</tt>: <tt><a>liftIO</a></tt>, enabling us to run
--   the program and see the expected results:
--   
--   <pre>
--   &gt; evalStateT printState "hello"
--   "hello"
--   
--   &gt; evalStateT printState 3
--   3
--   </pre>
liftIO :: MonadIO m => IO a -> m a

-- | Monads which allow their actions to be run in <a>IO</a>.
--   
--   While <a>MonadIO</a> allows an <a>IO</a> action to be lifted into
--   another monad, this class captures the opposite concept: allowing you
--   to capture the monadic context. Note that, in order to meet the laws
--   given below, the intuition is that a monad must have no monadic state,
--   but may have monadic context. This essentially limits
--   <a>MonadUnliftIO</a> to <a>ReaderT</a> and <a>IdentityT</a>
--   transformers on top of <a>IO</a>.
--   
--   Laws. For any function <tt>run</tt> provided by <a>withRunInIO</a>, it
--   must meet the monad transformer laws as reformulated for
--   <tt>MonadUnliftIO</tt>:
--   
--   <ul>
--   <li><pre>run . return = return</pre></li>
--   <li><pre>run (m &gt;&gt;= f) = run m &gt;&gt;= run . f</pre></li>
--   </ul>
--   
--   Instances of <tt>MonadUnliftIO</tt> must also satisfy the following
--   laws:
--   
--   <ul>
--   <li><i>Identity law</i> <tt>withRunInIO (\run -&gt; run m) =
--   m</tt></li>
--   <li><i>Inverse law</i> <tt>withRunInIO (\_ -&gt; m) = liftIO
--   m</tt></li>
--   </ul>
--   
--   As an example of an invalid instance, a naive implementation of
--   <tt>MonadUnliftIO (StateT s m)</tt> might be
--   
--   <pre>
--   withRunInIO inner =
--     StateT $ \s -&gt;
--       withRunInIO $ \run -&gt;
--         inner (run . flip evalStateT s)
--   </pre>
--   
--   This breaks the identity law because the inner <tt>run m</tt> would
--   throw away any state changes in <tt>m</tt>.
class MonadIO m => MonadUnliftIO (m :: Type -> Type)

-- | Convenience function for capturing the monadic context and running an
--   <a>IO</a> action with a runner function. The runner function is used
--   to run a monadic action <tt>m</tt> in <tt>IO</tt>.
withRunInIO :: MonadUnliftIO m => ((forall a. () => m a -> IO a) -> IO b) -> m b


-- | Support for handling errors of a particular type, i.e. checked
--   exceptions.
--   
--   The <a>Error</a> effect is <b>not</b> a general mechanism for handling
--   regular exceptions, that's what functions from the <tt>exceptions</tt>
--   library are for (see <a>Control.Monad.Catch</a> for more information).
--   
--   In particular, regular exceptions of type <tt>e</tt> are distinct from
--   errors of type <tt>e</tt> and will <b>not</b> be caught by functions
--   from this module:
--   
--   <pre>
--   &gt;&gt;&gt; import qualified Control.Monad.Catch as E
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; boom = error "BOOM!"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; runEff . runError @ErrorCall $ boom `catchError` \_ (_::ErrorCall) -&gt; pure "caught"
--   *** Exception: BOOM!
--   ...
--   </pre>
--   
--   If you want to catch regular exceptions, you should use <a>catch</a>
--   (or a similar function):
--   
--   <pre>
--   &gt;&gt;&gt; runEff $ boom `E.catch` \(_::ErrorCall) -&gt; pure "caught"
--   "caught"
--   </pre>
--   
--   On the other hand, functions for safe finalization and management of
--   resources such as <a>finally</a> and <a>bracket</a> work as expected:
--   
--   <pre>
--   &gt;&gt;&gt; msg = liftIO . putStrLn
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; :{
--   runEff . runErrorNoCallStack @String $ do
--     E.bracket_ (msg "Beginning.")
--                (msg "Cleaning up.")
--                (msg "Computing." &gt;&gt; throwError "oops" &gt;&gt; msg "More.")
--   :}
--   Beginning.
--   Computing.
--   Cleaning up.
--   Left "oops"
--   </pre>
--   
--   <i>Note:</i> unlike the <a>ExceptT</a> monad transformer from the
--   <tt>transformers</tt> library, the order in which you handle the
--   <a>Error</a> effect with regard to other stateful effects does not
--   matter. Consider the following:
--   
--   <pre>
--   &gt;&gt;&gt; import qualified Control.Monad.State.Strict as T
--   
--   &gt;&gt;&gt; import qualified Control.Monad.Except as T
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; m1 = (T.modify (++ " there!") &gt;&gt; T.throwError "oops") `T.catchError` \_ -&gt; pure ()
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; (`T.runStateT` "Hi") . T.runExceptT $ m1
--   (Right (),"Hi there!")
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; T.runExceptT . (`T.runStateT` "Hi") $ m1
--   Right ((),"Hi")
--   </pre>
--   
--   Here, whether state updates within the <a>catchError</a> block are
--   discarded or not depends on the shape of the monad transformer stack,
--   which is surprising and can be a source of subtle bugs. On the other
--   hand:
--   
--   <pre>
--   &gt;&gt;&gt; import Effectful.State.Static.Local
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; m2 = (modify (++ " there!") &gt;&gt; throwError "oops") `catchError` \_ (_::String) -&gt; pure ()
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; runEff . runState "Hi" . runError @String $ m2
--   (Right (),"Hi there!")
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; runEff . runError @String . runState "Hi" $ m2
--   Right ((),"Hi there!")
--   </pre>
--   
--   Here, no matter the order of effects, state updates made within the
--   <tt>catchError</tt> block before the error happens always persist,
--   giving predictable behavior.
--   
--   <i>Hint:</i> if you'd like to reproduce the transactional behavior
--   with the <a>State</a> effect, appropriate usage of
--   <a>bracketOnError</a> will do the trick.
module Effectful.Error.Static

-- | Provide the ability to handle errors of type <tt>e</tt>.
data Error e :: Effect

-- | Handle errors of type <tt>e</tt>.
runError :: forall e es a. Eff (Error e : es) a -> Eff es (Either (CallStack, e) a)

-- | Handle errors of type <tt>e</tt>. In case of an error discard the
--   <a>CallStack</a>.
runErrorNoCallStack :: forall e es a. Eff (Error e : es) a -> Eff es (Either e a)

-- | Throw an error of type <tt>e</tt>.
throwError :: forall e es a. (HasCallStack, Error e :> es) => e -> Eff es a

-- | Handle an error of type <tt>e</tt>.
catchError :: forall e es a. Error e :> es => Eff es a -> (CallStack -> e -> Eff es a) -> Eff es a

-- | The same as <tt><a>flip</a> <a>catchError</a></tt>, which is useful in
--   situations where the code for the handler is shorter.
handleError :: forall e es a. Error e :> es => (CallStack -> e -> Eff es a) -> Eff es a -> Eff es a

-- | Similar to <a>catchError</a>, but returns an <a>Either</a> result
--   which is a <a>Right</a> if no error was thrown and a <a>Left</a>
--   otherwise.
tryError :: forall e es a. Error e :> es => Eff es a -> Eff es (Either (CallStack, e) a)

-- | Request a CallStack.
--   
--   NOTE: The implicit parameter <tt>?callStack :: CallStack</tt> is an
--   implementation detail and <b>should not</b> be considered part of the
--   <a>CallStack</a> API, we may decide to change the implementation in
--   the future.
type HasCallStack = ?callStack :: CallStack

-- | <a>CallStack</a>s are a lightweight method of obtaining a partial
--   call-stack at any point in the program.
--   
--   A function can request its call-site with the <a>HasCallStack</a>
--   constraint. For example, we can define
--   
--   <pre>
--   putStrLnWithCallStack :: HasCallStack =&gt; String -&gt; IO ()
--   </pre>
--   
--   as a variant of <tt>putStrLn</tt> that will get its call-site and
--   print it, along with the string given as argument. We can access the
--   call-stack inside <tt>putStrLnWithCallStack</tt> with
--   <a>callStack</a>.
--   
--   <pre>
--   &gt;&gt;&gt; :{
--   putStrLnWithCallStack :: HasCallStack =&gt; String -&gt; IO ()
--   putStrLnWithCallStack msg = do
--     putStrLn msg
--     putStrLn (prettyCallStack callStack)
--   :}
--   </pre>
--   
--   Thus, if we call <tt>putStrLnWithCallStack</tt> we will get a
--   formatted call-stack alongside our string.
--   
--   <pre>
--   &gt;&gt;&gt; putStrLnWithCallStack "hello"
--   hello
--   CallStack (from HasCallStack):
--     putStrLnWithCallStack, called at &lt;interactive&gt;:... in interactive:Ghci...
--   </pre>
--   
--   GHC solves <a>HasCallStack</a> constraints in three steps:
--   
--   <ol>
--   <li>If there is a <a>CallStack</a> in scope -- i.e. the enclosing
--   function has a <a>HasCallStack</a> constraint -- GHC will append the
--   new call-site to the existing <a>CallStack</a>.</li>
--   <li>If there is no <a>CallStack</a> in scope -- e.g. in the GHCi
--   session above -- and the enclosing definition does not have an
--   explicit type signature, GHC will infer a <a>HasCallStack</a>
--   constraint for the enclosing definition (subject to the monomorphism
--   restriction).</li>
--   <li>If there is no <a>CallStack</a> in scope and the enclosing
--   definition has an explicit type signature, GHC will solve the
--   <a>HasCallStack</a> constraint for the singleton <a>CallStack</a>
--   containing just the current call-site.</li>
--   </ol>
--   
--   <a>CallStack</a>s do not interact with the RTS and do not require
--   compilation with <tt>-prof</tt>. On the other hand, as they are built
--   up explicitly via the <a>HasCallStack</a> constraints, they will
--   generally not contain as much information as the simulated call-stacks
--   maintained by the RTS.
--   
--   A <a>CallStack</a> is a <tt>[(String, SrcLoc)]</tt>. The
--   <tt>String</tt> is the name of function that was called, the
--   <a>SrcLoc</a> is the call-site. The list is ordered with the most
--   recently called function at the head.
--   
--   NOTE: The intrepid user may notice that <a>HasCallStack</a> is just an
--   alias for an implicit parameter <tt>?callStack :: CallStack</tt>. This
--   is an implementation detail and <b>should not</b> be considered part
--   of the <a>CallStack</a> API, we may decide to change the
--   implementation in the future.
data CallStack

-- | Extract a list of call-sites from the <a>CallStack</a>.
--   
--   The list is ordered by most recent call.
getCallStack :: CallStack -> [([Char], SrcLoc)]

-- | Pretty print a <a>CallStack</a>.
prettyCallStack :: CallStack -> String
instance GHC.Classes.Eq Effectful.Error.Static.ErrorId
instance GHC.Show.Show Effectful.Error.Static.ErrorWrapper
instance GHC.Exception.Type.Exception Effectful.Error.Static.ErrorWrapper


-- | Dynamically dispatched effects.
module Effectful.Dispatch.Dynamic

-- | Send an operation of the given effect to its handler for execution.
send :: (HasCallStack, DispatchOf e ~ Dynamic, e :> es) => e (Eff es) a -> Eff es a

-- | Type signature of the effect handler.
type EffectHandler e es = forall a localEs. (HasCallStack, e :> localEs) => LocalEnv localEs es " Capture of the local environment for handling local 'Eff' computations when @e@ is a higher order effect." -> e (Eff localEs) a " The effect performed in the local environment." -> Eff es a

-- | Interpret an effect.
--   
--   <i>Note:</i> <a>interpret</a> can be turned into a <a>reinterpret</a>
--   with the use of <a>inject</a>.
interpret :: DispatchOf e ~ Dynamic => EffectHandler e es -> Eff (e : es) a -> Eff es a

-- | Interpret an effect using other, private effects.
--   
--   <pre>
--   <a>interpret</a> ≡ <a>reinterpret</a> <a>id</a>
--   </pre>
reinterpret :: DispatchOf e ~ Dynamic => (Eff handlerEs a -> Eff es b) -> EffectHandler e handlerEs -> Eff (e : es) a -> Eff es b

-- | Replace the handler of an existing effect with a new one.
--   
--   <i>Note:</i> this function allows for augmenting handlers with a new
--   functionality as the new handler can send operations to the old one.
--   
--   <pre>
--   &gt;&gt;&gt; :{
--     data E :: Effect where
--       Op :: E m ()
--     type instance DispatchOf E = Dynamic
--   :}
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; :{
--     runE :: IOE :&gt; es =&gt; Eff (E : es) a -&gt; Eff es a
--     runE = interpret $ \_ Op -&gt; liftIO (putStrLn "op")
--   :}
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; runEff . runE $ send Op
--   op
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; :{
--     augmentE :: (E :&gt; es, IOE :&gt; es) =&gt; Eff es a -&gt; Eff es a
--     augmentE = interpose $ \_ Op -&gt; liftIO (putStrLn "augmented op") &gt;&gt; send Op
--   :}
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; runEff . runE . augmentE $ send Op
--   augmented op
--   op
--   </pre>
interpose :: forall e es a. (DispatchOf e ~ Dynamic, e :> es) => EffectHandler e es -> Eff es a -> Eff es a

-- | Replace the handler of an existing effect with a new one that uses
--   other, private effects.
--   
--   <pre>
--   <a>interpose</a> ≡ <a>impose</a> <a>id</a>
--   </pre>
impose :: forall e es handlerEs a b. (DispatchOf e ~ Dynamic, e :> es) => (Eff handlerEs a -> Eff es b) -> EffectHandler e handlerEs -> Eff es a -> Eff es b

-- | Opaque representation of the <a>Eff</a> environment at the point of
--   calling the <a>send</a> function, i.e. right before the control is
--   passed to the effect handler.
--   
--   The second type variable represents effects of a handler and is needed
--   for technical reasons to guarantee soundness (see <a>SharedSuffix</a>
--   for more information).
data LocalEnv (localEs :: [Effect]) (handlerEs :: [Effect])

-- | Create a local unlifting function with the <a>SeqUnlift</a> strategy.
--   For the general version see <a>localUnlift</a>.
localSeqUnlift :: (HasCallStack, SharedSuffix es handlerEs) => LocalEnv localEs handlerEs -> ((forall r. Eff localEs r -> Eff es r) -> Eff es a) -> Eff es a

-- | Create a local unlifting function with the <a>SeqUnlift</a> strategy.
--   For the general version see <a>localUnliftIO</a>.
localSeqUnliftIO :: (HasCallStack, SharedSuffix es handlerEs, IOE :> es) => LocalEnv localEs handlerEs -> ((forall r. Eff localEs r -> IO r) -> IO a) -> Eff es a

-- | Create a local unlifting function with the given strategy.
localUnlift :: (HasCallStack, SharedSuffix es handlerEs) => LocalEnv localEs handlerEs -> UnliftStrategy -> ((forall r. Eff localEs r -> Eff es r) -> Eff es a) -> Eff es a

-- | Create a local unlifting function with the given strategy.
localUnliftIO :: (HasCallStack, SharedSuffix es handlerEs, IOE :> es) => LocalEnv localEs handlerEs -> UnliftStrategy -> ((forall r. Eff localEs r -> IO r) -> IO a) -> Eff es a

-- | Create a local lifting function with the <a>SeqUnlift</a> strategy.
--   For the general version see <a>localLift</a>.
localSeqLift :: (HasCallStack, SharedSuffix es handlerEs) => LocalEnv localEs handlerEs -> ((forall r. Eff es r -> Eff localEs r) -> Eff es a) -> Eff es a

-- | Create a local lifting function with the given strategy.
localLift :: (HasCallStack, SharedSuffix es handlerEs) => LocalEnv localEs handlerEs -> UnliftStrategy -> ((forall r. Eff es r -> Eff localEs r) -> Eff es a) -> Eff es a

-- | Utility for lifting <a>Eff</a> computations of type
--   
--   <pre>
--   <a>Eff</a> es a -&gt; <a>Eff</a> es b
--   </pre>
--   
--   to
--   
--   <pre>
--   <a>Eff</a> localEs a -&gt; <a>Eff</a> localEs b
--   </pre>
--   
--   <i>Note:</i> the computation must not run its argument in a different
--   thread, attempting to do so will result in a runtime error.
withLiftMap :: (HasCallStack, SharedSuffix es handlerEs) => LocalEnv localEs handlerEs -> ((forall a b. (Eff es a -> Eff es b) -> Eff localEs a -> Eff localEs b) -> Eff es r) -> Eff es r

-- | Utility for lifting <a>IO</a> computations of type
--   
--   <pre>
--   <a>IO</a> a -&gt; <a>IO</a> b
--   </pre>
--   
--   to
--   
--   <pre>
--   <a>Eff</a> localEs a -&gt; <a>Eff</a> localEs b
--   </pre>
--   
--   <i>Note:</i> the computation must not run its argument in a different
--   thread, attempting to do so will result in a runtime error.
--   
--   Useful e.g. for lifting the unmasking function in <a>mask</a>-like
--   computations:
--   
--   <pre>
--   &gt;&gt;&gt; :{
--   data Fork :: Effect where
--     ForkWithUnmask :: ((forall a. m a -&gt; m a) -&gt; m ()) -&gt; Fork m ThreadId
--   type instance DispatchOf Fork = Dynamic
--   :}
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; :{
--   runFork :: IOE :&gt; es =&gt; Eff (Fork : es) a -&gt; Eff es a
--   runFork = interpret $ \env (ForkWithUnmask m) -&gt; withLiftMapIO env $ \liftMap -&gt; do
--     localUnliftIO env (ConcUnlift Ephemeral $ Limited 1) $ \unlift -&gt; do
--       forkIOWithUnmask $ \unmask -&gt; unlift $ m $ liftMap unmask
--   :}
--   </pre>
withLiftMapIO :: (HasCallStack, SharedSuffix es handlerEs, IOE :> es) => LocalEnv localEs handlerEs -> ((forall a b. (IO a -> IO b) -> Eff localEs a -> Eff localEs b) -> Eff es r) -> Eff es r

-- | Create a local lifting and unlifting function with the given strategy.
--   
--   Useful for lifting complicated <a>Eff</a> computations where the
--   monadic action shows in both positive (as a result) and negative (as
--   an argument) position.
--   
--   <i>Note:</i> depending on the computation you're lifting
--   <a>localUnlift</a> along with <a>withLiftMap</a> might be enough and
--   is more efficient.
localLiftUnlift :: (HasCallStack, SharedSuffix es handlerEs) => LocalEnv localEs handlerEs -> UnliftStrategy -> ((forall r. Eff es r -> Eff localEs r) -> (forall r. Eff localEs r -> Eff es r) -> Eff es a) -> Eff es a

-- | Create a local unlifting function with the given strategy along with
--   an unrestricted lifting function.
--   
--   Useful for lifting complicated <a>IO</a> computations where the
--   monadic action shows in both positive (as a result) and negative (as
--   an argument) position.
--   
--   <i>Note:</i> depending on the computation you're lifting
--   <a>localUnliftIO</a> along with <a>withLiftMapIO</a> might be enough
--   and is more efficient.
localLiftUnliftIO :: (HasCallStack, SharedSuffix es handlerEs, IOE :> es) => LocalEnv localEs handlerEs -> UnliftStrategy -> ((forall r. IO r -> Eff localEs r) -> (forall r. Eff localEs r -> IO r) -> IO a) -> Eff es a

-- | Require that both effect stacks share an opaque suffix.
--   
--   Functions from the <a>localUnlift</a> family utilize this constraint
--   to guarantee sensible usage of unlifting functions.
--   
--   As an example, consider the following higher order effect:
--   
--   <pre>
--   &gt;&gt;&gt; :{
--     data E :: Effect where
--       E :: m a -&gt; E m a
--     type instance DispatchOf E = Dynamic
--   :}
--   </pre>
--   
--   Running local actions in a more specific environment is fine:
--   
--   <pre>
--   &gt;&gt;&gt; :{
--    runE1 :: Eff (E ': es) a -&gt; Eff es a
--    runE1 = interpret $ \env -&gt; \case
--      E m -&gt; runReader () $ do
--        localSeqUnlift env $ \unlift -&gt; unlift m
--   :}
--   </pre>
--   
--   Running local actions in a more general environment is fine:
--   
--   <pre>
--   &gt;&gt;&gt; :{
--    runE2 :: Eff (E ': es) a -&gt; Eff es a
--    runE2 = reinterpret (runReader ()) $ \env -&gt; \case
--      E m -&gt; raise $ do
--        localSeqUnlift env $ \unlift -&gt; unlift m
--   :}
--   </pre>
--   
--   However, running local actions in an unrelated environment is not fine
--   as this would make it possible to run anything within
--   <a>runPureEff</a>:
--   
--   <pre>
--   &gt;&gt;&gt; :{
--    runE3 :: Eff (E ': es) a -&gt; Eff es a
--    runE3 = reinterpret (runReader ()) $ \env -&gt; \case
--      E m -&gt; pure . runPureEff $ do
--        localSeqUnlift env $ \unlift -&gt; unlift m
--   :}
--   ...
--   ...Could not deduce (SharedSuffix '[] es)...
--   ...
--   </pre>
--   
--   Running local actions in a monomorphic effect stack is also not fine
--   as this makes a special case of the above possible:
--   
--   <pre>
--   &gt;&gt;&gt; :{
--    runE4 :: Eff '[E, IOE] a -&gt; Eff '[IOE] a
--    runE4 = interpret $ \env -&gt; \case
--      E m -&gt; pure . runPureEff $ do
--        localSeqUnlift env $ \unlift -&gt; unlift m
--   :}
--   ...
--   ...Running local actions in monomorphic effect stacks is not supported...
--   ...
--   </pre>
class SharedSuffix (es1 :: [Effect]) (es2 :: [Effect])

-- | Request a CallStack.
--   
--   NOTE: The implicit parameter <tt>?callStack :: CallStack</tt> is an
--   implementation detail and <b>should not</b> be considered part of the
--   <a>CallStack</a> API, we may decide to change the implementation in
--   the future.
type HasCallStack = ?callStack :: CallStack
instance Effectful.Dispatch.Dynamic.SharedSuffix es es
instance Effectful.Dispatch.Dynamic.SharedSuffix es1 es2 => Effectful.Dispatch.Dynamic.SharedSuffix (e : es1) es2
instance Effectful.Dispatch.Dynamic.SharedSuffix es1 es2 => Effectful.Dispatch.Dynamic.SharedSuffix es1 (e : es2)
instance (TypeError ...) => Effectful.Dispatch.Dynamic.SharedSuffix '[] '[]


-- | Provider of the <a>MonadFail</a> instance for <a>Eff</a>.
module Effectful.Fail

-- | Provide the ability to use the <a>MonadFail</a> instance of
--   <a>Eff</a>.
data Fail :: Effect
[Fail] :: String -> Fail m a

-- | Run the <a>Fail</a> effect via <a>Error</a>.
runFail :: Eff (Fail : es) a -> Eff es (Either String a)

-- | Run the <a>Fail</a> effect via the <a>MonadFail</a> instance for
--   <a>IO</a>.
runFailIO :: IOE :> es => Eff (Fail : es) a -> Eff es a


-- | The dynamically dispatched variant of the <a>Error</a> effect.
--   
--   <i>Note:</i> unless you plan to change interpretations at runtime,
--   it's recommended to use the statically dispatched variant, i.e.
--   <a>Effectful.Error.Static</a>.
module Effectful.Error.Dynamic

-- | Provide the ability to handle errors of type <tt>e</tt>.
data Error e :: Effect
[ThrowError] :: e -> Error e m a
[CatchError] :: m a -> (CallStack -> e -> m a) -> Error e m a

-- | Handle errors of type <tt>e</tt> (via <a>Effectful.Error.Static</a>).
runError :: Eff (Error e : es) a -> Eff es (Either (CallStack, e) a)

-- | Handle errors of type <tt>e</tt> (via <a>Effectful.Error.Static</a>).
--   In case of an error discard the <a>CallStack</a>.
runErrorNoCallStack :: Eff (Error e : es) a -> Eff es (Either e a)

-- | Throw an error of type <tt>e</tt>.
throwError :: (HasCallStack, Error e :> es) => e -> Eff es a

-- | Handle an error of type <tt>e</tt>.
catchError :: (HasCallStack, Error e :> es) => Eff es a -> (CallStack -> e -> Eff es a) -> Eff es a

-- | The same as <tt><a>flip</a> <a>catchError</a></tt>, which is useful in
--   situations where the code for the handler is shorter.
handleError :: Error e :> es => (CallStack -> e -> Eff es a) -> Eff es a -> Eff es a

-- | Similar to <a>catchError</a>, but returns an <a>Either</a> result
--   which is a <a>Right</a> if no error was thrown and a <a>Left</a>
--   otherwise.
tryError :: (HasCallStack, Error e :> es) => Eff es a -> Eff es (Either (CallStack, e) a)

-- | Request a CallStack.
--   
--   NOTE: The implicit parameter <tt>?callStack :: CallStack</tt> is an
--   implementation detail and <b>should not</b> be considered part of the
--   <a>CallStack</a> API, we may decide to change the implementation in
--   the future.
type HasCallStack = ?callStack :: CallStack

-- | <a>CallStack</a>s are a lightweight method of obtaining a partial
--   call-stack at any point in the program.
--   
--   A function can request its call-site with the <a>HasCallStack</a>
--   constraint. For example, we can define
--   
--   <pre>
--   putStrLnWithCallStack :: HasCallStack =&gt; String -&gt; IO ()
--   </pre>
--   
--   as a variant of <tt>putStrLn</tt> that will get its call-site and
--   print it, along with the string given as argument. We can access the
--   call-stack inside <tt>putStrLnWithCallStack</tt> with
--   <a>callStack</a>.
--   
--   <pre>
--   &gt;&gt;&gt; :{
--   putStrLnWithCallStack :: HasCallStack =&gt; String -&gt; IO ()
--   putStrLnWithCallStack msg = do
--     putStrLn msg
--     putStrLn (prettyCallStack callStack)
--   :}
--   </pre>
--   
--   Thus, if we call <tt>putStrLnWithCallStack</tt> we will get a
--   formatted call-stack alongside our string.
--   
--   <pre>
--   &gt;&gt;&gt; putStrLnWithCallStack "hello"
--   hello
--   CallStack (from HasCallStack):
--     putStrLnWithCallStack, called at &lt;interactive&gt;:... in interactive:Ghci...
--   </pre>
--   
--   GHC solves <a>HasCallStack</a> constraints in three steps:
--   
--   <ol>
--   <li>If there is a <a>CallStack</a> in scope -- i.e. the enclosing
--   function has a <a>HasCallStack</a> constraint -- GHC will append the
--   new call-site to the existing <a>CallStack</a>.</li>
--   <li>If there is no <a>CallStack</a> in scope -- e.g. in the GHCi
--   session above -- and the enclosing definition does not have an
--   explicit type signature, GHC will infer a <a>HasCallStack</a>
--   constraint for the enclosing definition (subject to the monomorphism
--   restriction).</li>
--   <li>If there is no <a>CallStack</a> in scope and the enclosing
--   definition has an explicit type signature, GHC will solve the
--   <a>HasCallStack</a> constraint for the singleton <a>CallStack</a>
--   containing just the current call-site.</li>
--   </ol>
--   
--   <a>CallStack</a>s do not interact with the RTS and do not require
--   compilation with <tt>-prof</tt>. On the other hand, as they are built
--   up explicitly via the <a>HasCallStack</a> constraints, they will
--   generally not contain as much information as the simulated call-stacks
--   maintained by the RTS.
--   
--   A <a>CallStack</a> is a <tt>[(String, SrcLoc)]</tt>. The
--   <tt>String</tt> is the name of function that was called, the
--   <a>SrcLoc</a> is the call-site. The list is ordered with the most
--   recently called function at the head.
--   
--   NOTE: The intrepid user may notice that <a>HasCallStack</a> is just an
--   alias for an implicit parameter <tt>?callStack :: CallStack</tt>. This
--   is an implementation detail and <b>should not</b> be considered part
--   of the <a>CallStack</a> API, we may decide to change the
--   implementation in the future.
data CallStack

-- | Extract a list of call-sites from the <a>CallStack</a>.
--   
--   The list is ordered by most recent call.
getCallStack :: CallStack -> [([Char], SrcLoc)]

-- | Pretty print a <a>CallStack</a>.
prettyCallStack :: CallStack -> String


-- | Provider of the <a>Alternative</a> and <a>MonadPlus</a> instance for
--   <a>Eff</a>.
module Effectful.NonDet

-- | Provide the ability to use the <a>Alternative</a> and <a>MonadPlus</a>
--   instance of <a>Eff</a>.
data NonDet :: Effect
[Empty] :: NonDet m a
[:<|>:] :: m a -> m a -> NonDet m a

-- | Policy of dealing with modifications to <b>thread local</b> state in
--   the environment in branches that end up calling the <a>Empty</a>
--   operation.
--   
--   <i>Note:</i> <a>OnEmptyKeep</a> is significantly faster as there is no
--   need to back up the environment on each call to <a>:&lt;|&gt;:</a>.
data OnEmptyPolicy

-- | Keep modifications on <a>Empty</a>.
OnEmptyKeep :: OnEmptyPolicy

-- | Rollback modifications on <a>Empty</a>.
OnEmptyRollback :: OnEmptyPolicy

-- | Run the <a>NonDet</a> effect with a given <a>OnEmptyPolicy</a>.
--   
--   <i>Note:</i> <a>:&lt;|&gt;:</a> executes the second computation if
--   (and only if) the first computation calls <a>Empty</a>.
runNonDet :: OnEmptyPolicy -> Eff (NonDet : es) a -> Eff es (Either CallStack a)

-- | Specialized version of <a>empty</a> with the <a>HasCallStack</a>
--   constraint for tracking purposes.
emptyEff :: (HasCallStack, NonDet :> es) => Eff es a

-- | Specialized version of <a>asum</a> with the <a>HasCallStack</a>
--   constraint for tracking purposes.
sumEff :: (HasCallStack, Foldable t, NonDet :> es) => t (Eff es a) -> Eff es a

-- | A monoid on applicative functors.
--   
--   If defined, <a>some</a> and <a>many</a> should be the least solutions
--   of the equations:
--   
--   <ul>
--   <li><pre><a>some</a> v = (:) <a>&lt;$&gt;</a> v <a>&lt;*&gt;</a>
--   <a>many</a> v</pre></li>
--   <li><pre><a>many</a> v = <a>some</a> v <a>&lt;|&gt;</a> <a>pure</a>
--   []</pre></li>
--   </ul>
class Applicative f => Alternative (f :: Type -> Type)

-- | The identity of <a>&lt;|&gt;</a>
empty :: Alternative f => f a

-- | An associative binary operation
(<|>) :: Alternative f => f a -> f a -> f a

-- | One or more.
some :: Alternative f => f a -> f [a]

-- | Zero or more.
many :: Alternative f => f a -> f [a]
infixl 3 <|>

-- | Request a CallStack.
--   
--   NOTE: The implicit parameter <tt>?callStack :: CallStack</tt> is an
--   implementation detail and <b>should not</b> be considered part of the
--   <a>CallStack</a> API, we may decide to change the implementation in
--   the future.
type HasCallStack = ?callStack :: CallStack

-- | <a>CallStack</a>s are a lightweight method of obtaining a partial
--   call-stack at any point in the program.
--   
--   A function can request its call-site with the <a>HasCallStack</a>
--   constraint. For example, we can define
--   
--   <pre>
--   putStrLnWithCallStack :: HasCallStack =&gt; String -&gt; IO ()
--   </pre>
--   
--   as a variant of <tt>putStrLn</tt> that will get its call-site and
--   print it, along with the string given as argument. We can access the
--   call-stack inside <tt>putStrLnWithCallStack</tt> with
--   <a>callStack</a>.
--   
--   <pre>
--   &gt;&gt;&gt; :{
--   putStrLnWithCallStack :: HasCallStack =&gt; String -&gt; IO ()
--   putStrLnWithCallStack msg = do
--     putStrLn msg
--     putStrLn (prettyCallStack callStack)
--   :}
--   </pre>
--   
--   Thus, if we call <tt>putStrLnWithCallStack</tt> we will get a
--   formatted call-stack alongside our string.
--   
--   <pre>
--   &gt;&gt;&gt; putStrLnWithCallStack "hello"
--   hello
--   CallStack (from HasCallStack):
--     putStrLnWithCallStack, called at &lt;interactive&gt;:... in interactive:Ghci...
--   </pre>
--   
--   GHC solves <a>HasCallStack</a> constraints in three steps:
--   
--   <ol>
--   <li>If there is a <a>CallStack</a> in scope -- i.e. the enclosing
--   function has a <a>HasCallStack</a> constraint -- GHC will append the
--   new call-site to the existing <a>CallStack</a>.</li>
--   <li>If there is no <a>CallStack</a> in scope -- e.g. in the GHCi
--   session above -- and the enclosing definition does not have an
--   explicit type signature, GHC will infer a <a>HasCallStack</a>
--   constraint for the enclosing definition (subject to the monomorphism
--   restriction).</li>
--   <li>If there is no <a>CallStack</a> in scope and the enclosing
--   definition has an explicit type signature, GHC will solve the
--   <a>HasCallStack</a> constraint for the singleton <a>CallStack</a>
--   containing just the current call-site.</li>
--   </ol>
--   
--   <a>CallStack</a>s do not interact with the RTS and do not require
--   compilation with <tt>-prof</tt>. On the other hand, as they are built
--   up explicitly via the <a>HasCallStack</a> constraints, they will
--   generally not contain as much information as the simulated call-stacks
--   maintained by the RTS.
--   
--   A <a>CallStack</a> is a <tt>[(String, SrcLoc)]</tt>. The
--   <tt>String</tt> is the name of function that was called, the
--   <a>SrcLoc</a> is the call-site. The list is ordered with the most
--   recently called function at the head.
--   
--   NOTE: The intrepid user may notice that <a>HasCallStack</a> is just an
--   alias for an implicit parameter <tt>?callStack :: CallStack</tt>. This
--   is an implementation detail and <b>should not</b> be considered part
--   of the <a>CallStack</a> API, we may decide to change the
--   implementation in the future.
data CallStack

-- | Extract a list of call-sites from the <a>CallStack</a>.
--   
--   The list is ordered by most recent call.
getCallStack :: CallStack -> [([Char], SrcLoc)]

-- | Pretty print a <a>CallStack</a>.
prettyCallStack :: CallStack -> String
instance GHC.Show.Show Effectful.NonDet.OnEmptyPolicy
instance GHC.Classes.Ord Effectful.NonDet.OnEmptyPolicy
instance GHC.Generics.Generic Effectful.NonDet.OnEmptyPolicy
instance GHC.Classes.Eq Effectful.NonDet.OnEmptyPolicy


-- | Provider of the <tt>MonadPrim</tt> instance for <a>Eff</a>.
module Effectful.Prim

-- | Provide the ability to perform primitive state-transformer actions.
data Prim :: Effect

-- | <a>PrimState</a> token for <a>Eff</a>. Used instead of
--   <a>RealWorld</a> to prevent the <a>Prim</a> effect from executing
--   arbitrary <a>IO</a> actions via <a>ioToPrim</a>.
data PrimStateEff

-- | Run an <a>Eff</a> computation with primitive state-transformer
--   actions.
runPrim :: IOE :> es => Eff (Prim : es) a -> Eff es a


-- | Support for access to a read only value of a particular type.
module Effectful.Reader.Static

-- | Provide access to a strict (WHNF), thread local, read only value of
--   type <tt>r</tt>.
data Reader r :: Effect

-- | Run a <a>Reader</a> effect with the given initial environment.
runReader :: r -> Eff (Reader r : es) a -> Eff es a

-- | Execute a computation in a modified environment.
withReader :: (r1 -> r2) -> Eff (Reader r2 : es) a -> Eff (Reader r1 : es) a

-- | Fetch the value of the environment.
ask :: Reader r :> es => Eff es r

-- | Retrieve a function of the current environment.
--   
--   <pre>
--   <a>asks</a> f ≡ f <a>&lt;$&gt;</a> <a>ask</a>
--   </pre>
asks :: Reader r :> es => (r -> a) -> Eff es a

-- | Execute a computation in a modified environment.
--   
--   <pre>
--   <a>runReader</a> r (<a>local</a> f m) ≡ <a>runReader</a> (f r) m
--   </pre>
local :: Reader r :> es => (r -> r) -> Eff es a -> Eff es a


-- | The dynamically dispatched variant of the <a>Reader</a> effect.
--   
--   <i>Note:</i> unless you plan to change interpretations at runtime,
--   it's recommended to use the statically dispatched variant, i.e.
--   <a>Effectful.Reader.Static</a>.
module Effectful.Reader.Dynamic
data Reader r :: Effect
[Ask] :: Reader r m r
[Local] :: (r -> r) -> m a -> Reader r m a

-- | Run the <a>Reader</a> effect with the given initial environment (via
--   <a>Effectful.Reader.Static</a>).
runReader :: r -> Eff (Reader r : es) a -> Eff es a

-- | Execute a computation in a modified environment.
withReader :: (r1 -> r2) -> Eff (Reader r2 : es) a -> Eff (Reader r1 : es) a

-- | Fetch the value of the environment.
ask :: (HasCallStack, Reader r :> es) => Eff es r

-- | Retrieve a function of the current environment.
--   
--   <pre>
--   <a>asks</a> f ≡ f <a>&lt;$&gt;</a> <a>ask</a>
--   </pre>
asks :: (HasCallStack, Reader r :> es) => (r -> a) -> Eff es a

-- | Execute a computation in a modified environment.
--   
--   <pre>
--   <a>runReader</a> r (<a>local</a> f m) ≡ <a>runReader</a> (f r) m
--   </pre>
local :: (HasCallStack, Reader r :> es) => (r -> r) -> Eff es a -> Eff es a


-- | Support for access to a mutable value of a particular type.
--   
--   The value is thread local. If you want it to be shared between
--   threads, use <a>Effectful.State.Static.Shared</a>.
--   
--   <i>Note:</i> unlike the <a>StateT</a> monad transformer from the
--   <tt>transformers</tt> library, the <a>State</a> effect doesn't discard
--   state updates when an exception is received:
--   
--   <pre>
--   &gt;&gt;&gt; import qualified Control.Monad.Trans.State.Strict as S
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; :{
--     (`S.execStateT` "Hi") . handle (\(_::ErrorCall) -&gt; pure ()) $ do
--       S.modify (++ " there!")
--       error "oops"
--   :}
--   "Hi"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; :{
--     runEff . execState "Hi" . handle (\(_::ErrorCall) -&gt; pure ()) $ do
--       modify (++ " there!")
--       error "oops"
--   :}
--   "Hi there!"
--   </pre>
module Effectful.State.Static.Local

-- | Provide access to a strict (WHNF), thread local, mutable value of type
--   <tt>s</tt>.
data State s :: Effect

-- | Run the <a>State</a> effect with the given initial state and return
--   the final value along with the final state.
runState :: s -> Eff (State s : es) a -> Eff es (a, s)

-- | Run the <a>State</a> effect with the given initial state and return
--   the final value, discarding the final state.
evalState :: s -> Eff (State s : es) a -> Eff es a

-- | Run the <a>State</a> effect with the given initial state and return
--   the final state, discarding the final value.
execState :: s -> Eff (State s : es) a -> Eff es s

-- | Fetch the current value of the state.
get :: State s :> es => Eff es s

-- | Get a function of the current state.
--   
--   <pre>
--   <a>gets</a> f ≡ f <a>&lt;$&gt;</a> <a>get</a>
--   </pre>
gets :: State s :> es => (s -> a) -> Eff es a

-- | Set the current state to the given value.
put :: State s :> es => s -> Eff es ()

-- | Apply the function to the current state and return a value.
state :: State s :> es => (s -> (a, s)) -> Eff es a

-- | Apply the function to the current state.
--   
--   <pre>
--   <a>modify</a> f ≡ <a>state</a> (\s -&gt; ((), f s))
--   </pre>
modify :: State s :> es => (s -> s) -> Eff es ()

-- | Apply the monadic function to the current state and return a value.
stateM :: State s :> es => (s -> Eff es (a, s)) -> Eff es a

-- | Apply the monadic function to the current state.
--   
--   <pre>
--   <a>modifyM</a> f ≡ <a>stateM</a> (\s -&gt; ((), ) <a>&lt;$&gt;</a> f s)
--   </pre>
modifyM :: State s :> es => (s -> Eff es s) -> Eff es ()


-- | Support for access to a shared, mutable value of a particular type.
--   
--   The value is shared between multiple threads. If you want each thead
--   to manage its own version of the value, use
--   <a>Effectful.State.Static.Local</a>.
--   
--   <i>Note:</i> unlike the <a>StateT</a> monad transformer from the
--   <tt>transformers</tt> library, the <a>State</a> effect doesn't discard
--   state updates when an exception is received:
--   
--   <pre>
--   &gt;&gt;&gt; import qualified Control.Monad.Trans.State.Strict as S
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; :{
--     (`S.execStateT` "Hi") . handle (\(_::ErrorCall) -&gt; pure ()) $ do
--       S.modify (++ " there!")
--       error "oops"
--   :}
--   "Hi"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; :{
--     runEff . execState "Hi" . handle (\(_::ErrorCall) -&gt; pure ()) $ do
--       modify (++ " there!")
--       error "oops"
--   :}
--   "Hi there!"
--   </pre>
module Effectful.State.Static.Shared

-- | Provide access to a strict (WHNF), shared, mutable value of type
--   <tt>s</tt>.
data State s :: Effect

-- | Run the <a>State</a> effect with the given initial state and return
--   the final value along with the final state.
runState :: s -> Eff (State s : es) a -> Eff es (a, s)

-- | Run the <a>State</a> effect with the given initial state and return
--   the final value, discarding the final state.
evalState :: s -> Eff (State s : es) a -> Eff es a

-- | Run the <a>State</a> effect with the given initial state and return
--   the final state, discarding the final value.
execState :: s -> Eff (State s : es) a -> Eff es s

-- | Run the <a>State</a> effect with the given initial state <a>MVar</a>
--   and return the final value along with the final state.
runStateMVar :: MVar s -> Eff (State s : es) a -> Eff es (a, s)

-- | Run the <a>State</a> effect with the given initial state <a>MVar</a>
--   and return the final value, discarding the final state.
evalStateMVar :: MVar s -> Eff (State s : es) a -> Eff es a

-- | Run the <a>State</a> effect with the given initial state <a>MVar</a>
--   and return the final state, discarding the final value.
execStateMVar :: MVar s -> Eff (State s : es) a -> Eff es s

-- | Fetch the current value of the state.
get :: State s :> es => Eff es s

-- | Get a function of the current state.
--   
--   <pre>
--   <a>gets</a> f ≡ f <a>&lt;$&gt;</a> <a>get</a>
--   </pre>
gets :: State s :> es => (s -> a) -> Eff es a

-- | Set the current state to the given value.
put :: State s :> es => s -> Eff es ()

-- | Apply the function to the current state and return a value.
--   
--   <i>Note:</i> this function gets an exclusive access to the state for
--   its duration.
state :: State s :> es => (s -> (a, s)) -> Eff es a

-- | Apply the function to the current state.
--   
--   <pre>
--   <a>modify</a> f ≡ <a>state</a> (\s -&gt; ((), f s))
--   </pre>
--   
--   <i>Note:</i> this function gets an exclusive access to the state for
--   its duration.
modify :: State s :> es => (s -> s) -> Eff es ()

-- | Apply the monadic function to the current state and return a value.
--   
--   <i>Note:</i> this function gets an exclusive access to the state for
--   its duration.
stateM :: State s :> es => (s -> Eff es (a, s)) -> Eff es a

-- | Apply the monadic function to the current state.
--   
--   <pre>
--   <a>modifyM</a> f ≡ <a>stateM</a> (\s -&gt; ((), ) <a>&lt;$&gt;</a> f s)
--   </pre>
--   
--   <i>Note:</i> this function gets an exclusive access to the state for
--   its duration.
modifyM :: State s :> es => (s -> Eff es s) -> Eff es ()


-- | The dynamically dispatched variant of the <a>State</a> effect.
--   
--   <i>Note:</i> unless you plan to change interpretations at runtime,
--   it's recommended to use one of the statically dispatched variants,
--   i.e. <a>Effectful.State.Static.Local</a> or
--   <a>Effectful.State.Static.Shared</a>.
module Effectful.State.Dynamic

-- | Provide access to a mutable value of type <tt>s</tt>.
data State s :: Effect
[Get] :: State s m s
[Put] :: s -> State s m ()
[State] :: (s -> (a, s)) -> State s m a
[StateM] :: (s -> m (a, s)) -> State s m a

-- | Run the <a>State</a> effect with the given initial state and return
--   the final value along with the final state (via
--   <a>Effectful.State.Static.Local</a>).
runStateLocal :: s -> Eff (State s : es) a -> Eff es (a, s)

-- | Run the <a>State</a> effect with the given initial state and return
--   the final value, discarding the final state (via
--   <a>Effectful.State.Static.Local</a>).
evalStateLocal :: s -> Eff (State s : es) a -> Eff es a

-- | Run the <a>State</a> effect with the given initial state and return
--   the final state, discarding the final value (via
--   <a>Effectful.State.Static.Local</a>).
execStateLocal :: s -> Eff (State s : es) a -> Eff es s

-- | Run the <a>State</a> effect with the given initial state and return
--   the final value along with the final state (via
--   <a>Effectful.State.Static.Shared</a>).
runStateShared :: s -> Eff (State s : es) a -> Eff es (a, s)

-- | Run the <a>State</a> effect with the given initial state and return
--   the final value, discarding the final state (via
--   <a>Effectful.State.Static.Shared</a>).
evalStateShared :: s -> Eff (State s : es) a -> Eff es a

-- | Run the <a>State</a> effect with the given initial state and return
--   the final state, discarding the final value (via
--   <a>Effectful.State.Static.Shared</a>).
execStateShared :: s -> Eff (State s : es) a -> Eff es s

-- | Fetch the current value of the state.
get :: (HasCallStack, State s :> es) => Eff es s

-- | Get a function of the current state.
--   
--   <pre>
--   <a>gets</a> f ≡ f <a>&lt;$&gt;</a> <a>get</a>
--   </pre>
gets :: (HasCallStack, State s :> es) => (s -> a) -> Eff es a

-- | Set the current state to the given value.
put :: (HasCallStack, State s :> es) => s -> Eff es ()

-- | Apply the function to the current state and return a value.
state :: (HasCallStack, State s :> es) => (s -> (a, s)) -> Eff es a

-- | Apply the function to the current state.
--   
--   <pre>
--   <a>modify</a> f ≡ <a>state</a> (\s -&gt; ((), f s))
--   </pre>
modify :: (HasCallStack, State s :> es) => (s -> s) -> Eff es ()

-- | Apply the monadic function to the current state and return a value.
stateM :: (HasCallStack, State s :> es) => (s -> Eff es (a, s)) -> Eff es a

-- | Apply the monadic function to the current state.
--   
--   <pre>
--   <a>modifyM</a> f ≡ <a>stateM</a> (\s -&gt; ((), ) <a>&lt;$&gt;</a> f s)
--   </pre>
modifyM :: (HasCallStack, State s :> es) => (s -> Eff es s) -> Eff es ()


-- | Support for access to a write only value of a particular type.
--   
--   The value is thread local. If you want it to be shared between
--   threads, use <a>Effectful.Writer.Static.Shared</a>.
--   
--   <i>Warning:</i> <a>Writer</a>'s state will be accumulated via
--   <b>left-associated</b> uses of <a>&lt;&gt;</a>, which makes it
--   unsuitable for use with types for which such pattern is inefficient.
--   <b>This applies, in particular, to the standard list type</b>, which
--   makes the <a>Writer</a> effect pretty niche.
--   
--   <i>Note:</i> while the <a>Writer</a> from the <tt>transformers</tt>
--   package includes additional operations <a>pass</a> and <a>censor</a>,
--   they don't cooperate with runtime exceptions very well, so they're
--   deliberately omitted here.
module Effectful.Writer.Static.Local

-- | Provide access to a strict (WHNF), thread local, write only value of
--   type <tt>w</tt>.
data Writer w :: Effect

-- | Run a <a>Writer</a> effect and return the final value along with the
--   final output.
runWriter :: Monoid w => Eff (Writer w : es) a -> Eff es (a, w)

-- | Run a <a>Writer</a> effect and return the final output, discarding the
--   final value.
execWriter :: Monoid w => Eff (Writer w : es) a -> Eff es w

-- | Append the given output to the overall output of the <a>Writer</a>.
tell :: (Writer w :> es, Monoid w) => w -> Eff es ()

-- | Execute an action and append its output to the overall output of the
--   <a>Writer</a>.
--   
--   <i>Note:</i> if an exception is received while the action is executed,
--   the partial output of the action will still be appended to the overall
--   output of the <a>Writer</a>:
--   
--   <pre>
--   &gt;&gt;&gt; :{
--     runEff . execWriter @String $ do
--       tell "Hi"
--       handle (\(_::ErrorCall) -&gt; pure ((), "")) $ do
--         tell " there"
--         listen $ do
--           tell "!"
--           error "oops"
--   :}
--   "Hi there!"
--   </pre>
listen :: (Writer w :> es, Monoid w) => Eff es a -> Eff es (a, w)

-- | Execute an action and append its output to the overall output of the
--   <a>Writer</a>, then return the final value along with a function of
--   the recorded output.
--   
--   <pre>
--   <a>listens</a> f m ≡ <a>second</a> f <a>&lt;$&gt;</a> <a>listen</a> m
--   </pre>
listens :: (Writer w :> es, Monoid w) => (w -> b) -> Eff es a -> Eff es (a, b)


-- | Support for access to a write only value of a particular type.
--   
--   The value is shared between multiple threads. If you want each thead
--   to manage its own version of the value, use
--   <a>Effectful.Writer.Static.Local</a>.
--   
--   <i>Warning:</i> <a>Writer</a>'s state will be accumulated via
--   <b>left-associated</b> uses of <a>&lt;&gt;</a>, which makes it
--   unsuitable for use with types for which such pattern is inefficient.
--   <b>This applies, in particular, to the standard list type</b>, which
--   makes the <a>Writer</a> effect pretty niche.
--   
--   <i>Note:</i> while the <a>Writer</a> from the <tt>transformers</tt>
--   package includes additional operations <a>pass</a> and <a>censor</a>,
--   they don't cooperate with runtime exceptions very well, so they're
--   deliberately omitted here.
module Effectful.Writer.Static.Shared

-- | Provide access to a strict (WHNF), shared, write only value of type
--   <tt>w</tt>.
data Writer w :: Effect

-- | Run a <a>Writer</a> effect and return the final value along with the
--   final output.
runWriter :: Monoid w => Eff (Writer w : es) a -> Eff es (a, w)

-- | Run a <a>Writer</a> effect and return the final output, discarding the
--   final value.
execWriter :: Monoid w => Eff (Writer w : es) a -> Eff es w

-- | Append the given output to the overall output of the <a>Writer</a>.
tell :: (Writer w :> es, Monoid w) => w -> Eff es ()

-- | Execute an action and append its output to the overall output of the
--   <a>Writer</a>.
--   
--   <i>Note:</i> if an exception is received while the action is executed,
--   the partial output of the action will still be appended to the overall
--   output of the <a>Writer</a>:
--   
--   <pre>
--   &gt;&gt;&gt; :{
--     runEff . execWriter @String $ do
--       tell "Hi"
--       handle (\(_::ErrorCall) -&gt; pure ((), "")) $ do
--         tell " there"
--         listen $ do
--           tell "!"
--           error "oops"
--   :}
--   "Hi there!"
--   </pre>
listen :: (Writer w :> es, Monoid w) => Eff es a -> Eff es (a, w)

-- | Execute an action and append its output to the overall output of the
--   <a>Writer</a>, then return the final value along with a function of
--   the recorded output.
--   
--   <pre>
--   <a>listens</a> f m ≡ <a>second</a> f <a>&lt;$&gt;</a> <a>listen</a> m
--   </pre>
listens :: (Writer w :> es, Monoid w) => (w -> b) -> Eff es a -> Eff es (a, b)


-- | The dynamically dispatched variant of the <a>Writer</a> effect.
--   
--   <i>Note:</i> unless you plan to change interpretations at runtime,
--   it's recommended to use one of the statically dispatched variants,
--   i.e. <a>Effectful.Writer.Static.Local</a> or
--   <a>Effectful.Writer.Static.Shared</a>.
module Effectful.Writer.Dynamic

-- | Provide access to a write only value of type <tt>w</tt>.
data Writer w :: Effect
[Tell] :: w -> Writer w m ()
[Listen] :: m a -> Writer w m (a, w)

-- | Run the <a>Writer</a> effect and return the final value along with the
--   final output (via <a>Effectful.Writer.Static.Local</a>).
runWriterLocal :: Monoid w => Eff (Writer w : es) a -> Eff es (a, w)

-- | Run a <a>Writer</a> effect and return the final output, discarding the
--   final value (via <a>Effectful.Writer.Static.Local</a>).
execWriterLocal :: Monoid w => Eff (Writer w : es) a -> Eff es w

-- | Run the <a>Writer</a> effect and return the final value along with the
--   final output (via <a>Effectful.Writer.Static.Shared</a>).
runWriterShared :: Monoid w => Eff (Writer w : es) a -> Eff es (a, w)

-- | Run the <a>Writer</a> effect and return the final output, discarding
--   the final value (via <a>Effectful.Writer.Static.Shared</a>).
execWriterShared :: Monoid w => Eff (Writer w : es) a -> Eff es w

-- | Append the given output to the overall output of the <a>Writer</a>.
tell :: (HasCallStack, Writer w :> es) => w -> Eff es ()

-- | Execute an action and append its output to the overall output of the
--   <a>Writer</a>.
listen :: (HasCallStack, Writer w :> es) => Eff es a -> Eff es (a, w)

-- | Execute an action and append its output to the overall output of the
--   <a>Writer</a>, then return the final value along with a function of
--   the recorded output.
--   
--   <pre>
--   <a>listens</a> f m ≡ <a>second</a> f <a>&lt;$&gt;</a> <a>listen</a> m
--   </pre>
listens :: (HasCallStack, Writer w :> es) => (w -> b) -> Eff es a -> Eff es (a, b)