A MonadDi allows interacting with a Di through a mtl-like monadic API, rather than through the “bare” API proposed by Di.Core.

Nevertheless, be aware that these two APIs are compatible, so you may choose to use the monadic API for some parts of your application, the “bare” API for some other parts, and everything will compose and behave as expected. Usually, runDiT is the boundary between these two APIs, although not necessarily.

Semantically, MonadDi m is a “reader monad” that carries as its environment a Di and natural transformation from STM to m.

Log a message with the given importance level.

This function returns immediately after queing the message for logging. The actual printing of the log message will happen in a different thread, asynchronously. If you want to explicitly wait for the message to be logged, then call flush afterwards.

Log messages are rendered in FIFO order, and their timestamp records the time when this log function was called, rather than the time when the log message is printed in the future.

Note regarding exceptions: Any exception thrown by natSTM will be thrown here. Synchronous exceptions that happen due to failures in the actual committing of the log message are handled by attempting to log the message to stderr as a fallback if possible. Asynchronous exceptions happening as part of the committing process will be thrown in a different thread, and are not not explicitly handled. Pure exceptions originating from the filter function will be thrown here. In practical terms, this means that unless you know what you are doing, you should just call log' without worrying about it ever throwing exceptions.

Block until all messages being logged have finished processing.

Manually calling flush is not usually necessary because all log messages are processed as soon as possible, and with ensures that no log message is left unprocessed. However, the actual printing of log messages happens asynchronously, meaning there might be log messages still waiting to be processed. A call to flush will block until all pending log messages have been processed.

Run the given action under a deeper path.

Require that any logged messages within the given action satisfy the given predicate in order to be accepted for processing. Logged messages that don't satisfy the predicate will be silently discarded.

Identity:

filter (\_ _ _ -> True)  ==  id

Composition:

filter (\l ps m -> f l ps m && g l ps m)  ==  filter f . filter g

Commutativity:

filter f . filter g  ==  filter g . filter f

Within the passed given m a, exceptions thrown with throwM could could be logged as a msg with a particular level if both the passed in function returns Just, and filter so allows it afterwards.

If the given function returns Nothing, then no logging is performed.

The returned Seq path will extend the path at the throw call site before sending the log. The leftmost path is closest to the root.

Composition:

onException f . onException g   ==   onException (g e *> f e)

Notice that the level, paths and msg resulting from g are discarded, yet its policy regarding whether to log or not is preserved in the same way as filter. That is, onException can't accept an exception already rejected by a previous use of onException, but it can reject a previously accepted one.

A DiT level path msg m is a “reader monad” that carries as its environment a Di level path msg and natural transformation from STM to m.

The most primitive way to build a DiT is through diT.

The most primitive way to run a DiT is through runDiT'.

Build a DiT.

forall nat di.
   runDiT' nat di (diT (\nat' di' -> pure (nat', di')))
       == pure (nat, di)

Run a DiT.

forall di.
   runDiT di (diT (\nat' di' -> pure (nat', di')))
       == pure (natSTM, di)

This is like runDiT', but specialized to run with an underlying MonadIO.

runDiT  ==  runDiT' (liftIO . atomically)

Please notice that runDiT doesn't perform a flush on the given Di before returning. You are responsible for doing that (or, more likely, new will do it for you).

Also, notice that runDiT is a monad morphism from DiT m to m.

Run a DiT.

forall nat di.
   runDiT' nat di (diT (\nat' di' -> pure (nat', di')))
       == pure (nat, di)

runDiT' is like runDiT. However it doesn't require a MonadIO constraint. Instead, it takes the natural transformation that will be used by natSTM as an argument.

First, this allows any monad that wraps IO without necessarily having a MonadIO instance to work with MonadDi. For example:

newtype Foo = Foo (IO a)
  deriving (Functor, Applicative, Monad)

runDiT' (Foo . atomically)
     :: Di level path msg
     -> DiT level path msg Foo a
     -> Foo a

Second, this allows m to be STM itself:

runDiT' id
     :: Di level path msg
     -> DiT level path msg STM a
     -> STM a

The semantics of logging from within STM are those of any other STM transaction: That is, a log message is commited only once to the outside world if and when the STM transaction succeeds. That is, the following example will only ever commit the log containing ly and my, and not the one containing lx and mx.

atomically $ runDiT' id $ do
   (log id lx mx >> lift retry) <|>
   (log id ly my)

Of course, runDiT' works as well if you decide to wrap STM with your own monad type:

newtype Bar = Bar (STM a)
  deriving (Functor, Applicative, Monad)

runDiT' Bar
     :: Di level path msg
     -> DiT level path msg Bar a
     -> Bar a

Additionally, notice that runDiT' itself is a monad morphism from DiT level path msg m to m which doesn't perform any side effects of its own. Particularly, the given Di remains unaffected. So you can use it as many times you want.

forall f di x.
   runDiT' f di (lift x)  ==  x

Please notice that runDiT doesn't perform a flush on the given Di before returning. You are responsible for doing that (or, more likely, new will do it for you).

Lift a monad morphism from m to n to a monad morphism from DiT level path msg m to DiT n.

Notice that DiT itself is not a functor in the category of monads, so it can't be an instance of MFunctor from the mmorph package. However, it becomes one if you pair it with a natural transformation nat :: forall x. n x -> m x. That is:

forall nat.  such that nat is a natural transformation
   hoistDiT nat  ==  hoist

In practical terms, it means that most times you can “hoist” a DiT anyway, just not through hoist.

Run a DiT with a modified Di:

localDiT (const x) ask  ==  pure x

Notice that, contrary to local, this allows changing the type of Di, which means that you can use localDiT with contralevel, contrapath or contramsg to change the types of level, path, or message you DiT works with.

localDiT (contralevel (f :: level -> level'))
    :: DiT level' path msg m a
    -> DiT level path msg m a

localDiT (contrapath (f :: path -> path'))
    :: DiT level path' msg m a
    -> DiT level path msg m a

localDiT (contramsg (f :: msg -> msg'))
    :: DiT level path msg' m a
    -> DiT level path msg m a

Identity law:

localDiT id x  ==  x

Distributive law:

localDiT f . localDiT g  ==  localDiT (f . g)

Idempotence law:

localDiT f (pure ()) >> x  ==  x