Moduleeffectful-core-2.7.1.2GHC2021

Effectful.Internal.Env

10 types
23 values

Packageeffectful-core-2.7.1.2
Exports35
LanguageGHC2021
LicenceBSD-3-Clause
SourceEnv.hs

The environment

4 declarations

datadata Env (es :: [Effect])

A strict (WHNF), thread local, mutable, extensible record indexed by types of kind Effect.

Warning: the environment is a mutable data structure and cannot be simultaneously used from multiple threads under any circumstances.

In order to pass it to a different thread, you need to perform a deep copy with the cloneEnv function.

Offers very good performance characteristics for most often performed operations:

Extending: O(n), where n is the size of the effect stack.
Shrinking: O(1).
Indexing via (:>): O(1)
Modification of a specific element: O(1).
Getting a tail: O(1).
Cloning: O(N), where N is the size of the Storage.

Constructors

Env
- offset :: !Int
- refs :: !PrimArray Ref
- storage :: !IORef Storage

datadata Ref

Reference to the effect in Storage.

Constructors

Ref !Int !Version

Instances1Prim

Prim RefDefined in effectful-core-2.7.1.2 · Effectful.Internal.Env

newtypenewtype Version

Version of the effect.

Instances4Eq, Ord, Show, Prim

Eq VersionDefined in effectful-core-2.7.1.2 · Effectful.Internal.Env
Ord VersionDefined in effectful-core-2.7.1.2 · Effectful.Internal.Env
Show VersionDefined in effectful-core-2.7.1.2 · Effectful.Internal.Env
Prim VersionDefined in effectful-core-2.7.1.2 · Effectful.Internal.Env

datadata Storage

A storage of effects.

Constructors

Storage
- version :: !Version
- data_ :: !StorageData

StorageData

datadata StorageData

Constructors

StorageData
- size :: !Int
- versions :: !MutablePrimArray RealWorld Version
- effects :: !SmallMutableArray RealWorld AnyEffect
- relinkers :: !SmallMutableArray RealWorld AnyRelinker

valuecloneStorage :: HasCallStack => IORef Storage -> IO (IORef Storage)

Clone the storage to use it in a different thread.

valuereplaceStorage :: Env es -> IORef Storage -> IO (Env es)

Replace the storage of the environment.

valuebackupStorageData :: HasCallStack => Env es -> IO StorageData

Backup storage data of the environment.

It can be restored later with restoreStorageData.

valuerestoreStorageData :: HasCallStack => StorageData -> Env es -> IO ()

Restore a copy of the StorageData.

The copy needs to be from the same Env as the target. It's consumed by this operation and must not be used afterwards.

Utils

newtypenewtype AnyRelinker

Relinker in Storage.

valuetoAnyRelinker :: Relinker (EffectRep (DispatchOf e)) e -> AnyRelinker

valuefromAnyRelinker :: AnyRelinker -> Relinker (EffectRep (DispatchOf e)) e

newtypenewtype AnyEffect

Effect in Storage.

valuetoAnyEffect :: EffectRep (DispatchOf e) e -> AnyEffect

valuefromAnyEffect :: AnyEffect -> EffectRep (DispatchOf e) e

Relinker

newtypenewtype Relinker (a :: Effect -> Type) (b :: Effect) where

A function for relinking Env objects stored in the handlers and/or making a deep copy of the representation of the effect when cloning the environment.

Constructors

Relinker :: (HasCallStack => (forall (es :: [Effect]). Env es -> IO (Env es)) -> rep e -> IO (rep e)) -> Relinker a b

valuedummyRelinker :: Relinker rep e

A dummy Relinker.

Dispatch

4 declarations

datadata Dispatch

A type of dispatch. For more information consult the documentation in Effectful.Dispatch.Dynamic and Effectful.Dispatch.Static.

Constructors

Dynamic
Static SideEffects

datadata SideEffects

Signifies whether core operations of a statically dispatched effect perform side effects. If an effect is marked as such, the runStaticRep family of functions will require the IOE effect to be in context via the MaybeIOE type family.

NoSideEffects WithSideEffects

familytype family DispatchOf (e :: Effect) :: Dispatch

Dispatch types of effects.

Instances28DispatchOf, …

type DispatchOf Fail = 'DynamicDefined in effectful-core-2.7.1.2 · Effectful.Internal.Monad
type DispatchOf IOE = 'Static 'WithSideEffectsDefined in effectful-core-2.7.1.2 · Effectful.Internal.Monad
type DispatchOf NonDet = 'DynamicDefined in effectful-core-2.7.1.2 · Effectful.Internal.Monad
type DispatchOf Prim = 'Static 'WithSideEffectsDefined in effectful-core-2.7.1.2 · Effectful.Internal.Monad
type DispatchOf (Error e) = 'Static 'NoSideEffectsDefined in effectful-core-2.7.1.2 · Effectful.Error.Static
type DispatchOf (Input i) = 'DynamicDefined in effectful-core-2.7.1.2 · Effectful.Input.Dynamic
type DispatchOf (Input i) = 'Static 'NoSideEffectsDefined in effectful-core-2.7.1.2 · Effectful.Input.Static
type DispatchOf (Input i) = 'Static 'NoSideEffectsDefined in effectful-core-2.7.1.2 · Effectful.Input.Static.Action
type DispatchOf (Error e) = 'DynamicDefined in effectful-core-2.7.1.2 · Effectful.Internal.Effect.Dynamic
type DispatchOf (Reader r) = 'DynamicDefined in effectful-core-2.7.1.2 · Effectful.Internal.Effect.Dynamic
type DispatchOf (State s) = 'DynamicDefined in effectful-core-2.7.1.2 · Effectful.Internal.Effect.Dynamic
type DispatchOf (Writer w) = 'DynamicDefined in effectful-core-2.7.1.2 · Effectful.Internal.Effect.Dynamic
type DispatchOf (Labeled label e) = DispatchOf eDefined in effectful-core-2.7.1.2 · Effectful.Labeled
type DispatchOf (Output o) = 'DynamicDefined in effectful-core-2.7.1.2 · Effectful.Output.Dynamic
type DispatchOf (Output o) = 'Static 'NoSideEffectsDefined in effectful-core-2.7.1.2 · Effectful.Output.Static.Action
type DispatchOf (Output o) = 'Static 'NoSideEffectsDefined in effectful-core-2.7.1.2 · Effectful.Output.Static.Local.Array
type DispatchOf (Output o) = 'Static 'NoSideEffectsDefined in effectful-core-2.7.1.2 · Effectful.Output.Static.Local.List
type DispatchOf (Output o) = 'Static 'NoSideEffectsDefined in effectful-core-2.7.1.2 · Effectful.Output.Static.Shared.Array
type DispatchOf (Output o) = 'Static 'NoSideEffectsDefined in effectful-core-2.7.1.2 · Effectful.Output.Static.Shared.List
type DispatchOf (Provider e input f) = 'DynamicDefined in effectful-core-2.7.1.2 · Effectful.Provider
type DispatchOf (ProviderList providedEs input f) = 'DynamicDefined in effectful-core-2.7.1.2 · Effectful.Provider.List
type DispatchOf (Reader r) = 'Static 'NoSideEffectsDefined in effectful-core-2.7.1.2 · Effectful.Reader.Static
type DispatchOf (ReturnWith r) = 'DynamicDefined in effectful-core-2.7.1.2 · Effectful.ReturnWith.Dynamic
type DispatchOf (ReturnWith r) = 'Static 'NoSideEffectsDefined in effectful-core-2.7.1.2 · Effectful.ReturnWith.Static
type DispatchOf (State s) = 'Static 'NoSideEffectsDefined in effectful-core-2.7.1.2 · Effectful.State.Static.Local
type DispatchOf (State s) = 'Static 'NoSideEffectsDefined in effectful-core-2.7.1.2 · Effectful.State.Static.Shared
type DispatchOf (Writer w) = 'Static 'NoSideEffectsDefined in effectful-core-2.7.1.2 · Effectful.Writer.Static.Local
type DispatchOf (Writer w) = 'Static 'NoSideEffectsDefined in effectful-core-2.7.1.2 · Effectful.Writer.Static.Shared

familytype family EffectRep (d :: Dispatch) :: Effect -> Type

Internal representations of effects.

Instances2EffectRep

type EffectRep 'Dynamic = HandlerDefined in effectful-core-2.7.1.2 · Effectful.Internal.Monad · orphan
type EffectRep ('Static sideEffects) = StaticRepDefined in effectful-core-2.7.1.2 · Effectful.Internal.Monad · orphan

Operations

4 declarations

valueemptyEnv :: HasCallStack => IO (Env '[])

Create an empty environment.

valuecloneEnv :: HasCallStack => Env es -> IO (Env es)

Clone the environment to use it in a different thread.

valuesizeEnv :: Env es -> IO Int

Get the current size of the environment.

valuetailEnv :: Env (e ': es) -> IO (Env es)

Access the tail of the environment.

Modification of the effect stack

valueconsEnv

:: HasCallStack
=> EffectRep (DispatchOf e) e
The representation of the effect.
-> Relinker (EffectRep (DispatchOf e)) e
-> Env es
-> IO (Env (e ': es))

Extend the environment with a new data type.

valueunconsEnv :: HasCallStack => Env (e ': es) -> IO ()

Shrink the environment by one data type.

The environment needs to come from consEnv, i.e. the intended usage is bracket (consEnv e f env) unconsEnv.

Note: after calling this function e from the input environment is no longer usable.

valuereplaceEnv

:: (HasCallStack, e :> es)
=> EffectRep (DispatchOf e) e
The representation of the effect.
-> Relinker (EffectRep (DispatchOf e)) e
-> Env es
-> IO (Env es)

Replace a specific effect in the stack with a new value.

Note: unlike in putEnv the value is not changed in place, so only the new environment will see it.

valueunreplaceEnv :: (HasCallStack, e :> es) => Env es -> IO ()

Remove a reference to the replaced effect.

The environment needs to come from replaceEnv, i.e. the intended usage is bracket (replaceEnv e f env) unreplaceEnv.

Note: after calling this function the input environment is no longer usable.

valuesubsumeEnv :: e :> es => Env es -> IO (Env (e ': es))

Reference an existing effect from the top of the stack.

valueinjectEnv :: Subset subEs es => Env es -> IO (Env subEs)

Construct an environment containing a permutation (with possible duplicates) of a subset of effects from the input environment.

Data retrieval and update

valuegetEnv

:: (HasCallStack, e :> es)
=> Env es
The environment.
-> IO (EffectRep (DispatchOf e) e)

Extract a specific data type from the environment.

valueputEnv

:: (HasCallStack, e :> es)
=> Env es
The environment.
-> EffectRep (DispatchOf e) e
-> IO ()

Replace the data type in the environment with a new value (in place).

valuestateEnv

:: (HasCallStack, e :> es)
=> Env es
The environment.
-> (EffectRep (DispatchOf e) e -> (a, EffectRep (DispatchOf e) e))
-> IO a

Modify the data type in the environment and return a value (in place).

valuemodifyEnv

:: (HasCallStack, e :> es)
=> Env es
The environment.
-> (EffectRep (DispatchOf e) e -> EffectRep (DispatchOf e) e)
-> IO ()

Modify the data type in the environment (in place).