Documentation

A class for monads which provide for the ability to account for all possible exit points from a computation, and to mask asynchronous exceptions. Continuation-based monads are invalid instances of this class.

Instances should ensure that, in the following code:

fg = f `finally` g

The action g is called regardless of what occurs within f, including async exceptions. Some monads allow f to abort the computation via other effects than throwing an exception. For simplicity, we will consider aborting and throwing an exception to be two forms of "throwing an error".

If f and g both throw an error, the error thrown by fg depends on which errors we're talking about. In a monad transformer stack, the deeper layers override the effects of the inner layers; for example, ExceptT e1 (Except e2) a represents a value of type Either e2 (Either e1 a), so throwing both an e1 and an e2 will result in Left e2. If f and g both throw an error from the same layer, instances should ensure that the error from g wins.

Effects other than throwing an error are also overridden by the deeper layers. For example, StateT s Maybe a represents a value of type s -> Maybe (a, s), so if an error thrown from f causes this function to return Nothing, any changes to the state which f also performed will be erased. As a result, g will see the state as it was before f. Once g completes, f's error will be rethrown, so g' state changes will be erased as well. This is the normal interaction between effects in a monad transformer stack.

By contrast, lifted-base's version of finally always discards all of g's non-IO effects, and g never sees any of f's non-IO effects, regardless of the layer ordering and regardless of whether f throws an error. This is not the result of interacting effects, but a consequence of MonadBaseControl's approach.

This function lets us register structured, contextual info for the duration of the provided action. All messages logged within the provided action will automatically include this contextual info. This function is thread-safe, as the contextual info is scoped to the calling thread only.

This function is additive: if we nest calls to it, each nested call will add to the existing thread context. In the case of overlapping keys, the nested call's Pair value(s) will win. Whenever the inner action completes, the thread context is rolled back to its value set in the enclosing action.

If we wish to include the existing thread context from one thread in another thread, we must register the thread context explicitly on that other thread. myThreadContext can be leveraged in this case.

Registering thread context for messages can be useful in many scenarios. One particularly apt scenario is in wai middlewares. We can generate an ID for each incoming request then include it in the thread context. Now all messages subsequently logged from our endpoint handler will automatically include that request ID:

import Control.Monad.Logger.Aeson ((.=), withThreadContext)
import Network.Wai (Middleware)
import qualified Data.UUID.V4 as UUID

addRequestId :: Middleware
addRequestId app = \request sendResponse -> do
  uuid <- UUID.nextRandom
  withThreadContext ["requestId" .= uuid] do
    app request sendResponse

If we're coming from a Java background, it may be helpful for us to draw parallels between this function and log4j2's ThreadContext (or perhaps log4j's MDC). They all enable the same thing: setting some thread-local info that will be automatically pulled into each logged message.

Since: monad-logger-aeson-0.1.0.0

This function lets us retrieve the calling thread's thread context. For more detail, we can consult the docs for withThreadContext.

Note that even though the type signature lists MonadThrow as a required constraint, the library guarantees that myThreadContext will never throw.

Since: monad-logger-aeson-0.1.0.0

A key/value pair for an Object.