Add Haddock `/Since: 4.5.[01].0/` comments to symbols
[packages/base.git] / Debug / Trace.hs
1 {-# LANGUAGE Unsafe #-}
2 {-# LANGUAGE 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 traceId,
26 traceShow,
27 traceShowId,
28 traceStack,
29 traceIO,
30 traceM,
31 traceShowM,
32 putTraceMsg,
33
34 -- * Eventlog tracing
35 -- $eventlog_tracing
36 traceEvent,
37 traceEventIO,
38
39 -- * Execution phase markers
40 -- $markers
41 traceMarker,
42 traceMarkerIO,
43 ) where
44
45 import Prelude
46 import System.IO.Unsafe
47 import Control.Monad
48
49 import Foreign.C.String
50 import GHC.Base
51 import qualified GHC.Foreign
52 import GHC.IO.Encoding
53 import GHC.Ptr
54 import GHC.Stack
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 -- /Since: 4.5.0.0/
71 traceIO :: String -> IO ()
72 traceIO msg = do
73 withCString "%s\n" $ \cfmt ->
74 withCString msg $ \cmsg ->
75 debugBelch cfmt cmsg
76
77 -- don't use debugBelch() directly, because we cannot call varargs functions
78 -- using the FFI.
79 foreign import ccall unsafe "HsBase.h debugBelch2"
80 debugBelch :: CString -> CString -> IO ()
81
82 -- | Deprecated. Use 'traceIO'.
83 putTraceMsg :: String -> IO ()
84 putTraceMsg = traceIO
85 {-# DEPRECATED putTraceMsg "Use Debug.Trace.traceIO" #-} -- deprecated in 7.4
86
87
88 {-# NOINLINE trace #-}
89 {-|
90 The 'trace' function outputs the trace message given as its first argument,
91 before returning the second argument as its result.
92
93 For example, this returns the value of @f x@ but first outputs the message.
94
95 > trace ("calling f with x = " ++ show x) (f x)
96
97 The 'trace' function should /only/ be used for debugging, or for monitoring
98 execution. The function is not referentially transparent: its type indicates
99 that it is a pure function but it has the side effect of outputting the
100 trace message.
101 -}
102 trace :: String -> a -> a
103 trace string expr = unsafePerformIO $ do
104 traceIO string
105 return expr
106
107 {-|
108 Like 'trace' but returns the message instead of a third value.
109
110 /Since: 4.7.0.0/
111 -}
112 traceId :: String -> String
113 traceId a = trace a a
114
115 {-|
116 Like 'trace', but uses 'show' on the argument to convert it to a 'String'.
117
118 This makes it convenient for printing the values of interesting variables or
119 expressions inside a function. For example here we print the value of the
120 variables @x@ and @z@:
121
122 > f x y =
123 > traceShow (x, z) $ result
124 > where
125 > z = ...
126 > ...
127 -}
128 traceShow :: (Show a) => a -> b -> b
129 traceShow = trace . show
130
131 {-|
132 Like 'traceShow' but returns the shown value instead of a third value.
133
134 /Since: 4.7.0.0/
135 -}
136 traceShowId :: (Show a) => a -> a
137 traceShowId a = trace (show a) a
138
139 {-|
140 Like 'trace' but returning unit in an arbitrary monad. Allows for convenient
141 use in do-notation. Note that the application of 'trace' is not an action in the
142 monad, as 'traceIO' is in the 'IO' monad.
143
144 > ... = do
145 > x <- ...
146 > traceM $ "x: " ++ show x
147 > y <- ...
148 > traceM $ "y: " ++ show y
149
150 /Since: 4.7.0.0/
151 -}
152 traceM :: (Monad m) => String -> m ()
153 traceM string = trace string $ return ()
154
155 {-|
156 Like 'traceM', but uses 'show' on the argument to convert it to a 'String'.
157
158 > ... = do
159 > x <- ...
160 > traceMShow $ x
161 > y <- ...
162 > traceMShow $ x + y
163
164 /Since: 4.7.0.0/
165 -}
166 traceShowM :: (Show a, Monad m) => a -> m ()
167 traceShowM = traceM . show
168
169 -- | like 'trace', but additionally prints a call stack if one is
170 -- available.
171 --
172 -- In the current GHC implementation, the call stack is only
173 -- availble if the program was compiled with @-prof@; otherwise
174 -- 'traceStack' behaves exactly like 'trace'. Entries in the call
175 -- stack correspond to @SCC@ annotations, so it is a good idea to use
176 -- @-fprof-auto@ or @-fprof-auto-calls@ to add SCC annotations automatically.
177 --
178 -- /Since: 4.5.0.0/
179 traceStack :: String -> a -> a
180 traceStack str expr = unsafePerformIO $ do
181 traceIO str
182 stack <- currentCallStack
183 when (not (null stack)) $ traceIO (renderStack stack)
184 return expr
185
186
187 -- $eventlog_tracing
188 --
189 -- Eventlog tracing is a performance profiling system. These functions emit
190 -- extra events into the eventlog. In combination with eventlog profiling
191 -- tools these functions can be used for monitoring execution and
192 -- investigating performance problems.
193 --
194 -- Currently only GHC provides eventlog profiling, see the GHC user guide for
195 -- details on how to use it. These function exists for other Haskell
196 -- implementations but no events are emitted. Note that the string message is
197 -- always evaluated, whether or not profiling is available or enabled.
198
199 {-# NOINLINE traceEvent #-}
200 -- | The 'traceEvent' function behaves like 'trace' with the difference that
201 -- the message is emitted to the eventlog, if eventlog profiling is available
202 -- and enabled at runtime.
203 --
204 -- It is suitable for use in pure code. In an IO context use 'traceEventIO'
205 -- instead.
206 --
207 -- Note that when using GHC's SMP runtime, it is possible (but rare) to get
208 -- duplicate events emitted if two CPUs simultaneously evaluate the same thunk
209 -- that uses 'traceEvent'.
210 --
211 -- /Since: 4.5.0.0/
212 traceEvent :: String -> a -> a
213 traceEvent msg expr = unsafeDupablePerformIO $ do
214 traceEventIO msg
215 return expr
216
217 -- | The 'traceEventIO' function emits a message to the eventlog, if eventlog
218 -- profiling is available and enabled at runtime.
219 --
220 -- Compared to 'traceEvent', 'traceEventIO' sequences the event with respect to
221 -- other IO actions.
222 --
223 -- /Since: 4.5.0.0/
224 traceEventIO :: String -> IO ()
225 traceEventIO msg =
226 GHC.Foreign.withCString utf8 msg $ \(Ptr p) -> IO $ \s ->
227 case traceEvent# p s of s' -> (# s', () #)
228
229 -- $markers
230 --
231 -- When looking at a profile for the execution of a program we often want to
232 -- be able to mark certain points or phases in the execution and see that
233 -- visually in the profile.
234
235 -- For example, a program might have several distinct phases with different
236 -- performance or resource behaviour in each phase. To properly interpret the
237 -- profile graph we really want to see when each phase starts and ends.
238 --
239 -- Markers let us do this: we can annotate the program to emit a marker at
240 -- an appropriate point during execution and then see that in a profile.
241 --
242 -- Currently this feature is only supported in GHC by the eventlog tracing
243 -- system, but in future it may also be supported by the heap profiling or
244 -- other profiling tools. These function exists for other Haskell
245 -- implementations but they have no effect. Note that the string message is
246 -- always evaluated, whether or not profiling is available or enabled.
247
248 {-# NOINLINE traceMarker #-}
249 -- | The 'traceMarker' function emits a marker to the eventlog, if eventlog
250 -- profiling is available and enabled at runtime. The @String@ is the name of
251 -- the marker. The name is just used in the profiling tools to help you keep
252 -- clear which marker is which.
253 --
254 -- This function is suitable for use in pure code. In an IO context use
255 -- 'traceMarkerIO' instead.
256 --
257 -- Note that when using GHC's SMP runtime, it is possible (but rare) to get
258 -- duplicate events emitted if two CPUs simultaneously evaluate the same thunk
259 -- that uses 'traceMarker'.
260 --
261 -- /Since: 4.7.0.0/
262 traceMarker :: String -> a -> a
263 traceMarker msg expr = unsafeDupablePerformIO $ do
264 traceMarkerIO msg
265 return expr
266
267 -- | The 'traceMarkerIO' function emits a marker to the eventlog, if eventlog
268 -- profiling is available and enabled at runtime.
269 --
270 -- Compared to 'traceMarker', 'traceMarkerIO' sequences the event with respect to
271 -- other IO actions.
272 --
273 -- /Since: 4.7.0.0/
274 traceMarkerIO :: String -> IO ()
275 traceMarkerIO msg =
276 GHC.Foreign.withCString utf8 msg $ \(Ptr p) -> IO $ \s ->
277 case traceMarker# p s of s' -> (# s', () #)