Merge branch 'master' of http://darcs.haskell.org//packages/base
[packages/base.git] / Debug / Trace.hs
1 {-# LANGUAGE Unsafe #-}
2 {-# LANGUAGE CPP, ForeignFunctionInterface, MagicHash, UnboxedTuples #-}
3
4 -----------------------------------------------------------------------------
5 -- |
6 -- Module : Debug.Trace
7 -- Copyright : (c) The University of Glasgow 2001
8 -- License : BSD-style (see the file libraries/base/LICENSE)
9 --
10 -- Maintainer : libraries@haskell.org
11 -- Stability : provisional
12 -- Portability : portable
13 --
14 -- Functions for tracing and monitoring execution.
15 --
16 -- These can be useful for investigating bugs or performance problems.
17 -- They should /not/ be used in production code.
18 --
19 -----------------------------------------------------------------------------
20
21 module Debug.Trace (
22 -- * Tracing
23 -- $tracing
24 trace,
25 traceShow,
26 traceStack,
27 traceIO,
28 putTraceMsg,
29
30 -- * Eventlog tracing
31 -- $eventlog_tracing
32 traceEvent,
33 traceEventIO,
34
35 -- * Execution phase markers
36 -- $markers
37 traceMarker,
38 traceMarkerIO,
39 ) where
40
41 import Prelude
42 import System.IO.Unsafe
43 import Control.Monad
44
45 #ifdef __GLASGOW_HASKELL__
46 import Foreign.C.String
47 import GHC.Base
48 import qualified GHC.Foreign
49 import GHC.IO.Encoding
50 import GHC.Ptr
51 import GHC.Stack
52 #else
53 import System.IO (hPutStrLn,stderr)
54 #endif
55
56 -- $tracing
57 --
58 -- The 'trace', 'traceShow' and 'traceIO' functions print messages to an output
59 -- stream. They are intended for \"printf debugging\", that is: tracing the flow
60 -- of execution and printing interesting values.
61
62 -- The usual output stream is 'System.IO.stderr'. For Windows GUI applications
63 -- (that have no stderr) the output is directed to the Windows debug console.
64 -- Some implementations of these functions may decorate the string that\'s
65 -- output to indicate that you\'re tracing.
66
67 -- | The 'traceIO' function outputs the trace message from the IO monad.
68 -- This sequences the output with respect to other IO actions.
69 --
70 traceIO :: String -> IO ()
71 traceIO msg = do
72 #ifndef __GLASGOW_HASKELL__
73 hPutStrLn stderr msg
74 #else
75 withCString "%s\n" $ \cfmt ->
76 withCString msg $ \cmsg ->
77 debugBelch cfmt cmsg
78
79 -- don't use debugBelch() directly, because we cannot call varargs functions
80 -- using the FFI.
81 foreign import ccall unsafe "HsBase.h debugBelch2"
82 debugBelch :: CString -> CString -> IO ()
83 #endif
84
85
86 -- | Deprecated. Use 'traceIO'.
87 putTraceMsg :: String -> IO ()
88 putTraceMsg = traceIO
89 {-# DEPRECATED putTraceMsg "Use Debug.Trace.traceIO" #-}
90
91
92 {-# NOINLINE trace #-}
93 {-|
94 The 'trace' function outputs the trace message given as its first argument,
95 before returning the second argument as its result.
96
97 For example, this returns the value of @f x@ but first outputs the message.
98
99 > trace ("calling f with x = " ++ show x) (f x)
100
101 The 'trace' function should /only/ be used for debugging, or for monitoring
102 execution. The function is not referentially transparent: its type indicates
103 that it is a pure function but it has the side effect of outputting the
104 trace message.
105 -}
106 trace :: String -> a -> a
107 trace string expr = unsafePerformIO $ do
108 traceIO string
109 return expr
110
111 {-|
112 Like 'trace', but uses 'show' on the argument to convert it to a 'String'.
113
114 This makes it convenient for printing the values of interesting variables or
115 expressions inside a function. For example here we print the value of the
116 variables @x@ and @z@:
117
118 > f x y =
119 > traceShow (x, z) $ result
120 > where
121 > z = ...
122 > ...
123 -}
124 traceShow :: (Show a) => a -> b -> b
125 traceShow = trace . show
126
127 -- | like 'trace', but additionally prints a call stack if one is
128 -- available.
129 --
130 -- In the current GHC implementation, the call stack is only
131 -- availble if the program was compiled with @-prof@; otherwise
132 -- 'traceStack' behaves exactly like 'trace'. Entries in the call
133 -- stack correspond to @SCC@ annotations, so it is a good idea to use
134 -- @-fprof-auto@ or @-fprof-auto-calls@ to add SCC annotations automatically.
135 --
136 traceStack :: String -> a -> a
137 traceStack str expr = unsafePerformIO $ do
138 traceIO str
139 stack <- currentCallStack
140 when (not (null stack)) $ traceIO (renderStack stack)
141 return expr
142
143
144 -- $eventlog_tracing
145 --
146 -- Eventlog tracing is a performance profiling system. These functions emit
147 -- extra events into the eventlog. In combination with eventlog profiling
148 -- tools these functions can be used for monitoring execution and
149 -- investigating performance problems.
150 --
151 -- Currently only GHC provides eventlog profiling, see the GHC user guide for
152 -- details on how to use it. These function exists for other Haskell
153 -- implementations but no events are emitted. Note that the string message is
154 -- always evaluated, whether or not profiling is available or enabled.
155
156 {-# NOINLINE traceEvent #-}
157 -- | The 'traceEvent' function behaves like 'trace' with the difference that
158 -- the message is emitted to the eventlog, if eventlog profiling is available
159 -- and enabled at runtime.
160 --
161 -- It is suitable for use in pure code. In an IO context use 'traceEventIO'
162 -- instead.
163 --
164 -- Note that when using GHC's SMP runtime, it is possible (but rare) to get
165 -- duplicate events emitted if two CPUs simultaneously evaluate the same thunk
166 -- that uses 'traceEvent'.
167 --
168 traceEvent :: String -> a -> a
169 traceEvent msg expr = unsafeDupablePerformIO $ do
170 traceEventIO msg
171 return expr
172
173 -- | The 'traceEventIO' function emits a message to the eventlog, if eventlog
174 -- profiling is available and enabled at runtime.
175 --
176 -- Compared to 'traceEvent', 'traceEventIO' sequences the event with respect to
177 -- other IO actions.
178 --
179 traceEventIO :: String -> IO ()
180 #ifdef __GLASGOW_HASKELL__
181 traceEventIO msg =
182 GHC.Foreign.withCString utf8 msg $ \(Ptr p) -> IO $ \s ->
183 case traceEvent# p s of s' -> (# s', () #)
184 #else
185 traceEventIO msg = (return $! length msg) >> return ()
186 #endif
187
188
189 -- $markers
190 --
191 -- When looking at a profile for the execution of a program we often want to
192 -- be able to mark certain points or phases in the execution and see that
193 -- visually in the profile.
194
195 -- For example, a program might have several distinct phases with different
196 -- performance or resource behaviour in each phase. To properly interpret the
197 -- profile graph we really want to see when each phase starts and ends.
198 --
199 -- Markers let us do this: we can annotate the program to emit a marker at
200 -- an appropriate point during execution and then see that in a profile.
201 --
202 -- Currently this feature is only supported in GHC by the eventlog tracing
203 -- system, but in future it may also be supported by the heap profiling or
204 -- other profiling tools. These function exists for other Haskell
205 -- implementations but they have no effect. Note that the string message is
206 -- always evaluated, whether or not profiling is available or enabled.
207
208 {-# NOINLINE traceMarker #-}
209 -- | The 'traceMarker' function emits a marker to the eventlog, if eventlog
210 -- profiling is available and enabled at runtime. The @String@ is the name of
211 -- the marker. The name is just used in the profiling tools to help you keep
212 -- clear which marker is which.
213 --
214 -- This function is suitable for use in pure code. In an IO context use
215 -- 'traceMarkerIO' instead.
216 --
217 -- Note that when using GHC's SMP runtime, it is possible (but rare) to get
218 -- duplicate events emitted if two CPUs simultaneously evaluate the same thunk
219 -- that uses 'traceMarker'.
220 --
221 traceMarker :: String -> a -> a
222 traceMarker msg expr = unsafeDupablePerformIO $ do
223 traceMarkerIO msg
224 return expr
225
226 -- | The 'traceMarkerIO' function emits a marker to the eventlog, if eventlog
227 -- profiling is available and enabled at runtime.
228 --
229 -- Compared to 'traceMarker', 'traceMarkerIO' sequences the event with respect to
230 -- other IO actions.
231 --
232 traceMarkerIO :: String -> IO ()
233 #ifdef __GLASGOW_HASKELL__
234 traceMarkerIO msg =
235 GHC.Foreign.withCString utf8 msg $ \(Ptr p) -> IO $ \s ->
236 case traceMarker# p s of s' -> (# s', () #)
237 #else
238 traceMarkerIO msg = (return $! length msg) >> return ()
239 #endif
240