Effectful.Internal.Env

The environment

data 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 funtion.

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

Fields

• envOffset :: !Int
• envRefs :: !(PrimArray Ref)
• envStorage :: !(IORef' Storage)

data Ref

Reference to the effect in Storage.

Constructors

Ref !Int !Version

Instances

Prim Ref

Defined in Effectful.Internal.Env

Methods

sizeOfType# :: Proxy Ref -> Int#

sizeOf# :: Ref -> Int#

alignmentOfType# :: Proxy Ref -> Int#

alignment# :: Ref -> Int#

indexByteArray# :: ByteArray# -> Int# -> Ref

readByteArray# :: MutableByteArray# s -> Int# -> State# s -> (# State# s, Ref #)

writeByteArray# :: MutableByteArray# s -> Int# -> Ref -> State# s -> State# s

setByteArray# :: MutableByteArray# s -> Int# -> Int# -> Ref -> State# s -> State# s

indexOffAddr# :: Addr# -> Int# -> Ref

readOffAddr# :: Addr# -> Int# -> State# s -> (# State# s, Ref #)

writeOffAddr# :: Addr# -> Int# -> Ref -> State# s -> State# s

setOffAddr# :: Addr# -> Int# -> Int# -> Ref -> State# s -> State# s

data Version

Version of the effect.

Instances

Show Version

Defined in Effectful.Internal.Env

Methods

showsPrec :: Int -> Version -> ShowS

show :: Version -> String

showList :: [Version] -> ShowS

Eq Version

Defined in Effectful.Internal.Env

Methods

(==) :: Version -> Version -> Bool

(/=) :: Version -> Version -> Bool

Ord Version

Defined in Effectful.Internal.Env

Methods

compare :: Version -> Version -> Ordering

(<) :: Version -> Version -> Bool

(<=) :: Version -> Version -> Bool

(>) :: Version -> Version -> Bool

(>=) :: Version -> Version -> Bool

max :: Version -> Version -> Version

min :: Version -> Version -> Version

Prim Version

Defined in Effectful.Internal.Env

Methods

sizeOfType# :: Proxy Version -> Int#

sizeOf# :: Version -> Int#

alignmentOfType# :: Proxy Version -> Int#

alignment# :: Version -> Int#

indexByteArray# :: ByteArray# -> Int# -> Version

readByteArray# :: MutableByteArray# s -> Int# -> State# s -> (# State# s, Version #)

writeByteArray# :: MutableByteArray# s -> Int# -> Version -> State# s -> State# s

setByteArray# :: MutableByteArray# s -> Int# -> Int# -> Version -> State# s -> State# s

indexOffAddr# :: Addr# -> Int# -> Version

readOffAddr# :: Addr# -> Int# -> State# s -> (# State# s, Version #)

writeOffAddr# :: Addr# -> Int# -> Version -> State# s -> State# s

setOffAddr# :: Addr# -> Int# -> Int# -> Version -> State# s -> State# s

data Storage

A storage of effects.

Constructors

Storage

Fields

• stVersion :: !Version
• stData :: !StorageData

StorageData

data StorageData

Constructors

StorageData

Fields

• sdSize :: !Int
• sdVersions :: !(MutablePrimArray RealWorld Version)
• sdEffects :: !(SmallMutableArray RealWorld AnyEffect)
• sdRelinkers :: !(SmallMutableArray RealWorld AnyRelinker)

copyStorageData :: HasCallStack => StorageData -> IO StorageData

Make a shallow copy of the StorageData.

Since: 2.5.0.0

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

Restore a shallow copy of the StorageData.

The copy needs to be from the same Env as the target.

Since: 2.5.0.0

Utils

data AnyRelinker

Relinker in Storage.

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

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

data AnyEffect

Effect in Storage.

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

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

Relinker

newtype Relinker :: (Effect -> Type) -> Effect -> Type 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. Env es -> IO (Env es)) -> rep e -> IO (rep e)) -> Relinker rep e

dummyRelinker :: Relinker rep e

A dummy Relinker.

Dispatch

data Dispatch

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

Constructors

Dynamic

Static SideEffects

data 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.

Constructors

NoSideEffects

WithSideEffects

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

Dispatch types of effects.

Instances

type DispatchOf Fail

Defined in Effectful.Internal.Monad

type DispatchOf Fail = 'Dynamic

type DispatchOf IOE

Defined in Effectful.Internal.Monad

type DispatchOf IOE = 'Static 'WithSideEffects

type DispatchOf NonDet

Defined in Effectful.Internal.Monad

type DispatchOf NonDet = 'Dynamic

type DispatchOf Prim

Defined in Effectful.Internal.Monad

type DispatchOf Prim = 'Static 'WithSideEffects

type DispatchOf (Error e)

Defined in Effectful.Error.Dynamic

type DispatchOf (Error e) = 'Dynamic

type DispatchOf (Error e)

Defined in Effectful.Error.Static

type DispatchOf (Error e) = 'Static 'NoSideEffects

type DispatchOf (Reader r)

Defined in Effectful.Reader.Dynamic

type DispatchOf (Reader r) = 'Dynamic

type DispatchOf (Reader r)

Defined in Effectful.Reader.Static

type DispatchOf (Reader r) = 'Static 'NoSideEffects

type DispatchOf (State s)

Defined in Effectful.State.Dynamic

type DispatchOf (State s) = 'Dynamic

type DispatchOf (State s)

Defined in Effectful.State.Static.Local

type DispatchOf (State s) = 'Static 'NoSideEffects

type DispatchOf (State s)

Defined in Effectful.State.Static.Shared

type DispatchOf (State s) = 'Static 'NoSideEffects

type DispatchOf (Writer w)

Defined in Effectful.Writer.Dynamic

type DispatchOf (Writer w) = 'Dynamic

type DispatchOf (Writer w)

Defined in Effectful.Writer.Static.Local

type DispatchOf (Writer w) = 'Static 'NoSideEffects

type DispatchOf (Writer w)

Defined in Effectful.Writer.Static.Shared

type DispatchOf (Writer w) = 'Static 'NoSideEffects

type DispatchOf (Labeled label e)

Defined in Effectful.Labeled

type DispatchOf (Labeled label e) = DispatchOf e

type DispatchOf (Provider e input f)

Defined in Effectful.Provider

type DispatchOf (Provider e input f) = 'Static 'NoSideEffects

type DispatchOf (ProviderList providedEs input f)

Defined in Effectful.Provider.List

type DispatchOf (ProviderList providedEs input f) = 'Static 'NoSideEffects

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

Internal representations of effects.

Instances

type EffectRep 'Dynamic

Defined in Effectful.Internal.Monad

type EffectRep 'Dynamic = Handler

type EffectRep ('Static sideEffects)

Defined in Effectful.Internal.Monad

type EffectRep ('Static sideEffects) = StaticRep

Operations

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

Create an empty environment.

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

Clone the environment to use it in a different thread.

sizeEnv :: Env es -> IO Int

Get the current size of the environment.

tailEnv :: Env (e : es) -> IO (Env es)

Access the tail of the environment.

Modification of the effect stack

consEnv

Arguments

:: 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.

unconsEnv :: HasCallStack => Env (e : es) -> IO ()

Shrink the environment by one data type.

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

replaceEnv

Arguments

:: forall e es. (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 in not changed in place, so only the new environment will see it.

unreplaceEnv :: forall e es. (HasCallStack, e :> es) => Env es -> IO ()

Remove a reference to the replaced effect.

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

subsumeEnv :: forall e es. e :> es => Env es -> IO (Env (e : es))

Reference an existing effect from the top of the stack.

injectEnv :: forall subEs es. 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

getEnv

Arguments

:: forall e es. (HasCallStack, e :> es)

=> Env es

The environment.

-> IO (EffectRep (DispatchOf e) e)

Extract a specific data type from the environment.

putEnv

Arguments

:: forall e es. (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).

stateEnv

Arguments

:: forall e es a. (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).

modifyEnv

Arguments

:: forall e es. (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).