-- Hoogle documentation, generated by Haddock -- See Hoogle, http://www.haskell.org/hoogle/ -- | Utilities for making your applications more debuggable. -- -- This package provides various utilities that can be used to make your -- application easier to debug. Some of these tools are intended for use -- during actual debugging only (similar to Debug.Trace, for -- example). Other tools can be used as a regular component in your -- application, to facilitate debugging if and when necessary, but always -- present in your code. @package debuggable @version 0.1.0 -- | Functions for non-interleaved output -- -- Intended for qualifed import. -- -- 
--   import Debug.NonInterleavedIO qualified as NIIO
--
-- -- Alternatively, you can import Debug.NonInterleavedIO.Trace as a -- drop-in replacement for Debug.Trace. -- -- The functions in this module can all be called concurrently, without -- resulting in interleaved output: each function call is atomic. -- -- The first time any of these functions is called, we lookup the -- NIIO_OUTPUT environment variable. If set, we will write to -- the file specified (if the file already exists, it will be -- overwritten). If NIIO_OUTPUT is not set, a temporary file -- will be created in the system temporary directory; typically such a -- file will be called tmpniionumber. The name of -- this file is written to stderr (this is the only -- output origiating from functions in this module that is not written to -- the file). module Debug.NonInterleavedIO -- | Non-interleaved version of putStr putStr :: MonadIO m => String -> m () -- | Non-interleaved version of putStrLn putStrLn :: MonadIO m => String -> m () -- | Non-interleaved version of print print :: (MonadIO m, Show a) => a -> m () -- | Non-interleaved version of trace trace :: String -> a -> a -- | Non-interleaved version of traceShow traceShow :: Show a => a -> b -> b -- | Non-interleaved version of traceShowId traceShowId :: Show a => a -> a -- | Non-interleaved version of traceM traceM :: Applicative m => String -> m () -- | Non-interleaved version of traceShowM traceShowM :: (Applicative m, Show a) => a -> m () -- | Drop-in replacement for Debug.Trace -- -- This module just re-exports some functions from -- Debug.NonInterleavedIO; since it does not export anything that -- clashes with Prelude it can be imported unqualified. module Debug.NonInterleavedIO.Trace -- | Non-interleaved version of trace trace :: String -> a -> a -- | Non-interleaved version of traceShow traceShow :: Show a => a -> b -> b -- | Non-interleaved version of traceShowId traceShowId :: Show a => a -> a -- | Non-interleaved version of traceM traceM :: Applicative m => String -> m () -- | Non-interleaved version of traceShowM traceShowM :: (Applicative m, Show a) => a -> m () -- | Provenance for callbacks module Debug.Provenance.Callback -- | Callback of type (a -> m b) -- -- When we invoke a callback, it is useful to distinguish between two -- things: -- -- -- -- The purpose of this module is to be careful about this distinction; a -- HasCallStack backtrace originating from an invocation of a -- callback will look something like this: -- -- 
--   gM, called at ..
--   ..
--   g2, called at ..
--   g1, called at ..
--   callbackFn, called at ..
--   invoking callback defined at <callSite>
--   invokeCallback, called at ..
--   fN, called at ..
--   ..
--   f2, called at ..
--   f1, called at ..
--
-- -- where -- -- data Callback (m :: Type -> Type) a b -- | Define Callback -- -- See Callback for discussion and motivation of the two -- HasCallStack constraints. callback :: HasCallStack => (HasCallStack => a -> m b) -> Callback m a b -- | Invoke Callback invokeCallback :: HasCallStack => Callback m a b -> a -> m b -- | 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 type HasCallStack = ?callStack :: CallStack -- | Utilities for tracking provenance: where and when things are called module Debug.Provenance -- | 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. data CallSite -- | Render CallSite to human-readable format prettyCallSite :: CallSite -> String -- | Current CallSite callSite :: HasCallStack => CallSite -- | Current CallSite with user-defined label callSiteWithLabel :: HasCallStack => String -> CallSite -- | 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. data Invocation -- | Render Invocation to human-readable format prettyInvocation :: Invocation -> String -- | New invocation -- -- See Invocation for discussion. newInvocation :: (HasCallStack, MonadIO m) => m Invocation -- | 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 type HasCallStack = ?callStack :: CallStack -- | Utilities for tracking scope: nested Invocations -- -- Intended for unqualified import. module Debug.Provenance.Scope -- | Thread-local scope -- -- Most recent invocations are first in the list. type Scope = [Invocation] -- | Extend current scope scoped :: (HasCallStack, MonadMask m, MonadIO m) => m a -> m a -- | Get current scope getScope :: MonadIO m => m Scope -- | Convenience combination of forkIO and inheritScope forkInheritScope :: IO () -> IO ThreadId -- | Inherit scope from a parent thread -- -- This sets the scope of the current thread to that of the parent. This -- should be done prior to growing the scope of the child thread; -- inheritScope will fail with an exception if the scope in the -- child thread is not empty. -- -- See also forkInheritScope. inheritScope :: MonadIO m => ThreadId -> m () -- | 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 type HasCallStack = ?callStack :: CallStack -- | Utilities for writing debugging messages that include provenance -- -- Intended for qualified import. -- -- 
--   import Debug.NonInterleavedIO.Scoped qualified as Scoped
--
module Debug.NonInterleavedIO.Scoped -- | Print debug message, showing current scope putStrLn :: (HasCallStack, MonadIO m) => String -> m ()