Observe.Event.BackendModification

A domain-specific language for modifying the behavior of EventBackends, needed when the caller can't specify the EventBackend to use directly.

The instrumented capability problem

A common approach for polymorphic effect management in Haskell is the "capability pattern", where a function polymorphic in some monad m takes as an argument a value also polymorphic in m that can be used to run a constrained set of effects in m. One example of such a "capability" type would be EventBackend, which for example enables running newEvent in whatever m it's instantiated in. These capabilities are often themselves implemented in terms of other capabilities, and are ultimately concretely instantiated in some base monad (typically IO, or perhaps ST for a pure mock) and then hoisted to the application's monadic context (e.g. hoistEventBackend).

Normally this compose + hoist approach works fine, since any capabilities that are dependencies of the the capability we're hoisting are hidden in its closure. But if a capability depends on an EventBackend for instrumentation, closing over it at creation time causes a problem: at the call-site of the various effects enabled by the capability, we have no way to modify the EventBackend to e.g. be a noop (because we don't need the details of this effect's actions to instrument the calling function effectively) or to have its Events descend from some current Event. Thus, the DSL defined in this module: effects which take some polymorphic capability can *also* take an EventBackendModifier and the capability can modify its captured EventBackend with modifyEventBackend accordingly.

An alternative would be to have each effect in the capability take an EventBackend at the call site. This would foreclose hoisting along an arbitrary natural transformation, since the EventBackend would be in negative position, but constrained hoisting might be possible with MonadUnliftIO or MonadUnlift or MonadBaseControl if we share a base monad, or if we implemented EventBackends in a separate base monad that appears in the type of our capabilities and ensure it's liftable to both our application monad and the capability's base instantiation.

Documentation

data EventBackendModifier r r' where

Modify an EventBackend, chaging its reference type from r to r'

Constructors

Silence :: forall r. EventBackendModifier r ()

Ignore all instrumentation using the EventBackend

SetAncestor

Mark every parentless event as the child of a known Event.

Fields

• :: forall r. r

  A reference to the parent Event.

• -> EventBackendModifier r r

SetInitialCause

Mark every causeless event as proximately caused by a known Event.

Fields

• :: forall r. r

  A reference to the causing Event.

• -> EventBackendModifier r r

data EventBackendModifiers r r'

A sequence of EventBackendModifiers

The free Category over EventBackendModifier

Instances

Category EventBackendModifiers

Defined in Observe.Event.BackendModification

Methods

id :: forall (a :: k). EventBackendModifiers a a

(.) :: forall (b :: k) (c :: k) (a :: k). EventBackendModifiers b c -> EventBackendModifiers a b -> EventBackendModifiers a c

modifyEventBackend :: Monad m => EventBackendModifiers r r' -> EventBackend m r s -> EventBackend m r' s

Modify an EventBackend according to the given EventBackendModifiers.

This is a right fold, e.g. modifyEventBackend (a . b . id) backend first modifies backend with b and then modifies the result with a.

Simple EventBackendModifiers

unmodified :: EventBackendModifiers r r

An EventBackendModifiers that does nothing.

silence :: EventBackendModifiers r ()

An EventBackendModifiers that silences events.

setAncestor :: r -> EventBackendModifiers r r

An EventBackendModifiers that marks every parentless event as the child of a known Event.

setInitialCause :: r -> EventBackendModifiers r r

An EventBackendModifiers that marks every causeless event as proximately caused by a known Event.