-----------------------------------------------------------------------------
-- |
-- 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