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, which itself is performed in a different thread, are ignored (they should be handled in the function passed to new instead). If an asynchronous exception kills the logging thread, then you will synchronously get ExceptionInLoggingWorker here, but by the time that happens, that same exception will have already already been thrown asynchronously to this same thread anyway, so unless you did something funny to recover from that exception, you will have died already.

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.

Please see log to understand how exceptions behave in this function (hint: they behave unsurprisingly).

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

Throw an Exception, but not without logging it first according to the rules established by onException, and further restricted by the rules established by filter.

If the exception doesn't need to be logged, according to the policy set with onException, then this function behaves just as throwSTM.

WARNING: Note that when m is STM, or ultimately runs on STM, then throw will not log the exception, just throw it. This might change in the future if we figure out how to make it work safely.

Within the passed given m a, exceptions thrown with throw 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 level path msg 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