Debug.Provenance

Utilities for tracking provenance: where and when things are called

Callsites

data CallSite

Callsite

A callsite tells you where something was called: a location in the source, and the name of the function that did the calling. Optionally, they can be given an additional user-defined label also.

NOTE: If you are seeing {unknown} instead of the function name, the calling function does not have a HasCallStack annotation:

yourFunction :: HasCallStack => IO () -- 'HasCallStack' probably missing
yourFunction = do
    let cs = callSite
    ..

Once you add this annotation, you should see yourFunction instead of {unknown}. Similarly, if you have local function definitions, it may be useful to give those HasCallStack constraints of their own:

yourFunction :: HasCallStack => IO ()
yourFunction = ..
  where
    someLocalFn :: HasCallStack => IO ()
    someLocalFn = do
        let cs = callSite
        ..

In this example the HasCallStack constraint on someLocalFn means that the calling function will be reported as someLocalFn instead of yourFunction.

Instances

Show CallSite

Defined in Debug.Provenance.Internal

Methods

showsPrec :: Int -> CallSite -> ShowS

show :: CallSite -> String

showList :: [CallSite] -> ShowS

Eq CallSite

Defined in Debug.Provenance.Internal

Methods

(==) :: CallSite -> CallSite -> Bool

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

Hashable CallSite

Defined in Debug.Provenance.Internal

Methods

hashWithSalt :: Int -> CallSite -> Int

hash :: CallSite -> Int

prettyCallSite :: CallSite -> String

Render CallSite to human-readable format

callSite :: HasCallStack => CallSite

Current CallSite

callSiteWithLabel :: HasCallStack => String -> CallSite

Current CallSite with user-defined label

Invocations

data Invocation

Invocation

An invocation not only tells you the where, but also the when: it pairs a CallSite with a count, automatically incremented on each call to newInvocation. Each CallSite uses its own counter.

Instances

Show Invocation

Defined in Debug.Provenance.Internal

Methods

showsPrec :: Int -> Invocation -> ShowS

show :: Invocation -> String

showList :: [Invocation] -> ShowS

Eq Invocation

Defined in Debug.Provenance.Internal

Methods

(==) :: Invocation -> Invocation -> Bool

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

prettyInvocation :: Invocation -> String

Render Invocation to human-readable format

newInvocation :: (HasCallStack, MonadIO m) => m Invocation

New invocation

See Invocation for discussion.

Convenience re-exports

type HasCallStack = ?callStack :: CallStack

Request a CallStack.

NOTE: The implicit parameter ?callStack :: CallStack is an implementation detail and should not be considered part of the CallStack API, we may decide to change the implementation in the future.

@since base-4.9.0.0