    -----------------------------------------------------------------------------
    -- |
    -- Module      :  GHC.ExecutionStack
    -- Copyright   :  (c) The University of Glasgow 2013-2015
    -- License     :  see libraries/base/LICENSE
    --
    -- Maintainer  :  cvs-ghc@haskell.org
    -- Stability   :  internal
    -- Portability :  non-portable (GHC Extensions)
    --
    -- This is a module for efficient stack traces. This stack trace implementation
    -- is considered low overhead. Basic usage looks like this:
    --
    -- @
    -- import GHC.ExecutionStack
    --
    -- myFunction :: IO ()
    -- myFunction = do
    --      putStrLn =<< showStackTrace
    -- @
    --
    -- Your GHC must have been built with @libdw@ support for this to work.
    --
    -- @
    -- user@host:~$ ghc --info | grep libdw
    --  ,("RTS expects libdw","YES")
    -- @
    --
    -- @since 4.9.0.0
    -----------------------------------------------------------------------------

    module GHC.ExecutionStack (
        Location (..)
      , SrcLoc (..)
      , getStackTrace
      , showStackTrace
      ) where

    import Control.Monad (join)
    import GHC.ExecutionStack.Internal

    -- | Get a trace of the current execution stack state.
    --
    -- Returns @Nothing@ if stack trace support isn't available on host machine.
    getStackTrace :: IO (Maybe [Location])
    getStackTrace :: IO (Maybe [Location])
    getStackTrace = (Maybe (Maybe [Location]) -> Maybe [Location]
    forall (m :: * -> *) a. Monad m => m (m a) -> m a
    join (Maybe (Maybe [Location]) -> Maybe [Location])
    -> (Maybe StackTrace -> Maybe (Maybe [Location]))
    -> Maybe StackTrace
    -> Maybe [Location]
    forall b c a. (b -> c) -> (a -> b) -> a -> c
    . (StackTrace -> Maybe [Location])
    -> Maybe StackTrace -> Maybe (Maybe [Location])
    forall a b. (a -> b) -> Maybe a -> Maybe b
    forall (f :: * -> *) a b. Functor f => (a -> b) -> f a -> f b
    fmap StackTrace -> Maybe [Location]
    stackFrames) (Maybe StackTrace -> Maybe [Location])
    -> IO (Maybe StackTrace) -> IO (Maybe [Location])
    forall a b. (a -> b) -> IO a -> IO b
    forall (f :: * -> *) a b. Functor f => (a -> b) -> f a -> f b
    `fmap` IO (Maybe StackTrace)
    collectStackTrace

    -- | Get a string representation of the current execution stack state.
    showStackTrace :: IO (Maybe String)
    showStackTrace :: IO (Maybe String)
    showStackTrace = ([Location] -> String) -> Maybe [Location] -> Maybe String
    forall a b. (a -> b) -> Maybe a -> Maybe b
    forall (f :: * -> *) a b. Functor f => (a -> b) -> f a -> f b
    fmap (\[Location]
    st -> [Location] -> ShowS
    showStackFrames [Location]
    st String
    "") (Maybe [Location] -> Maybe String)
    -> IO (Maybe [Location]) -> IO (Maybe String)
    forall a b. (a -> b) -> IO a -> IO b
    forall (f :: * -> *) a b. Functor f => (a -> b) -> f a -> f b
    `fmap` IO (Maybe [Location])
    getStackTrace