Don't infer CallStacks
[ghc.git] / libraries / base / GHC / Stack / Types.hs
1 {-# LANGUAGE NoImplicitPrelude #-}
2 {-# LANGUAGE ConstraintKinds #-}
3 {-# LANGUAGE ImplicitParams #-}
4 {-# LANGUAGE KindSignatures #-}
5 {-# LANGUAGE PolyKinds #-}
6 {-# LANGUAGE RankNTypes #-}
7
8 {-# OPTIONS_HADDOCK hide #-}
9 -- we hide this module from haddock to enforce GHC.Stack as the main
10 -- access point.
11
12 -----------------------------------------------------------------------------
13 -- |
14 -- Module : GHC.Stack.Types
15 -- Copyright : (c) The University of Glasgow 2015
16 -- License : see libraries/ghc-prim/LICENSE
17 --
18 -- Maintainer : cvs-ghc@haskell.org
19 -- Stability : internal
20 -- Portability : non-portable (GHC Extensions)
21 --
22 -- type definitions for implicit call-stacks.
23 -- Use "GHC.Stack" from the base package instead of importing this
24 -- module directly.
25 --
26 -----------------------------------------------------------------------------
27
28 module GHC.Stack.Types (
29 -- * Implicit call stacks
30 CallStack(..), HasCallStack,
31 emptyCallStack, freezeCallStack, fromCallSiteList,
32 getCallStack, pushCallStack,
33
34 -- * Source locations
35 SrcLoc(..)
36 ) where
37
38 {-
39 Ideally these would live in GHC.Stack but sadly they can't due to this
40 import cycle,
41
42 Module imports form a cycle:
43 module ‘Data.Maybe’ (libraries/base/Data/Maybe.hs)
44 imports ‘GHC.Base’ (libraries/base/GHC/Base.hs)
45 which imports ‘GHC.Err’ (libraries/base/GHC/Err.hs)
46 which imports ‘GHC.Stack’ (libraries/base/dist-install/build/GHC/Stack.hs)
47 which imports ‘GHC.Foreign’ (libraries/base/GHC/Foreign.hs)
48 which imports ‘Data.Maybe’ (libraries/base/Data/Maybe.hs)
49 -}
50
51 import GHC.Classes (Eq)
52 import GHC.Types
53
54 -- Make implicit dependency known to build system
55 import GHC.Tuple ()
56 import GHC.Integer ()
57
58 ----------------------------------------------------------------------
59 -- Explicit call-stacks built via ImplicitParams
60 ----------------------------------------------------------------------
61
62 -- | Request a CallStack.
63 --
64 -- NOTE: The implicit parameter @?callStack :: CallStack@ is an
65 -- implementation detail and __should not__ be considered part of the
66 -- 'CallStack' API, we may decide to change the implementation in the
67 -- future.
68 --
69 -- @since 4.9.0.0
70 type HasCallStack = (?callStack :: CallStack)
71
72 -- | 'CallStack's are a lightweight method of obtaining a
73 -- partial call-stack at any point in the program.
74 --
75 -- A function can request its call-site with the 'HasCallStack' constraint.
76 -- For example, we can define
77 --
78 -- @
79 -- errorWithCallStack :: HasCallStack => String -> a
80 -- @
81 --
82 -- as a variant of @error@ that will get its call-site. We can access the
83 -- call-stack inside @errorWithCallStack@ with 'GHC.Stack.callStack'.
84 --
85 -- @
86 -- errorWithCallStack :: HasCallStack => String -> a
87 -- errorWithCallStack msg = error (msg ++ "\n" ++ prettyCallStack callStack)
88 -- @
89 --
90 -- Thus, if we call @errorWithCallStack@ we will get a formatted call-stack
91 -- alongside our error message.
92 --
93 --
94 -- >>> errorWithCallStack "die"
95 -- *** Exception: die
96 -- CallStack (from HasCallStack):
97 -- errorWithCallStack, called at <interactive>:2:1 in interactive:Ghci1
98 --
99 --
100 -- GHC solves 'HasCallStack' constraints in three steps:
101 --
102 -- 1. If there is a 'CallStack' in scope -- i.e. the enclosing function
103 -- has a 'HasCallStack' constraint -- GHC will append the new
104 -- call-site to the existing 'CallStack'.
105 --
106 -- 2. If there is no 'CallStack' in scope -- e.g. in the GHCi session
107 -- above -- and the enclosing definition does not have an explicit
108 -- type signature, GHC will infer a 'HasCallStack' constraint for the
109 -- enclosing definition (subject to the monomorphism restriction).
110 --
111 -- 3. If there is no 'CallStack' in scope and the enclosing definition
112 -- has an explicit type signature, GHC will solve the 'HasCallStack'
113 -- constraint for the singleton 'CallStack' containing just the
114 -- current call-site.
115 --
116 -- 'CallStack's do not interact with the RTS and do not require compilation
117 -- with @-prof@. On the other hand, as they are built up explicitly via the
118 -- 'HasCallStack' constraints, they will generally not contain as much
119 -- information as the simulated call-stacks maintained by the RTS.
120 --
121 -- A 'CallStack' is a @[(String, SrcLoc)]@. The @String@ is the name of
122 -- function that was called, the 'SrcLoc' is the call-site. The list is
123 -- ordered with the most recently called function at the head.
124 --
125 -- NOTE: The intrepid user may notice that 'HasCallStack' is just an
126 -- alias for an implicit parameter @?callStack :: CallStack@. This is an
127 -- implementation detail and __should not__ be considered part of the
128 -- 'CallStack' API, we may decide to change the implementation in the
129 -- future.
130 --
131 -- @since 4.8.1.0
132 data CallStack
133 = EmptyCallStack
134 | PushCallStack [Char] SrcLoc CallStack
135 | FreezeCallStack CallStack
136 -- ^ Freeze the stack at the given @CallStack@, preventing any further
137 -- call-sites from being pushed onto it.
138
139 -- See Note [Overview of implicit CallStacks]
140
141 -- | Extract a list of call-sites from the 'CallStack'.
142 --
143 -- The list is ordered by most recent call.
144 --
145 -- @since 4.8.1.0
146 getCallStack :: CallStack -> [([Char], SrcLoc)]
147 getCallStack stk = case stk of
148 EmptyCallStack -> []
149 PushCallStack fn loc stk' -> (fn,loc) : getCallStack stk'
150 FreezeCallStack stk' -> getCallStack stk'
151
152 -- | Convert a list of call-sites to a 'CallStack'.
153 --
154 -- @since 4.9.0.0
155 fromCallSiteList :: [([Char], SrcLoc)] -> CallStack
156 fromCallSiteList ((fn,loc):cs) = PushCallStack fn loc (fromCallSiteList cs)
157 fromCallSiteList [] = EmptyCallStack
158
159 -- Note [Definition of CallStack]
160 -- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
161 -- CallStack is defined very early in base because it is
162 -- used by error and undefined. At this point in the dependency graph,
163 -- we do not have enough functionality to (conveniently) write a nice
164 -- pretty-printer for CallStack. The sensible place to define the
165 -- pretty-printer would be GHC.Stack, which is the main access point,
166 -- but unfortunately GHC.Stack imports GHC.Exception, which *needs*
167 -- the pretty-printer. So the CallStack type and functions are split
168 -- between three modules:
169 --
170 -- 1. GHC.Stack.Types: defines the type and *simple* functions
171 -- 2. GHC.Exception: defines the pretty-printer
172 -- 3. GHC.Stack: exports everything and acts as the main access point
173
174
175 -- | Push a call-site onto the stack.
176 --
177 -- This function has no effect on a frozen 'CallStack'.
178 --
179 -- @since 4.9.0.0
180 pushCallStack :: ([Char], SrcLoc) -> CallStack -> CallStack
181 pushCallStack (fn, loc) stk = case stk of
182 FreezeCallStack _ -> stk
183 _ -> PushCallStack fn loc stk
184 {-# INLINE pushCallStack #-}
185
186
187 -- | The empty 'CallStack'.
188 --
189 -- @since 4.9.0.0
190 emptyCallStack :: CallStack
191 emptyCallStack = EmptyCallStack
192 {-# INLINE emptyCallStack #-}
193
194
195 -- | Freeze a call-stack, preventing any further call-sites from being appended.
196 --
197 -- prop> pushCallStack callSite (freezeCallStack callStack) = freezeCallStack callStack
198 --
199 -- @since 4.9.0.0
200 freezeCallStack :: CallStack -> CallStack
201 freezeCallStack stk = FreezeCallStack stk
202 {-# INLINE freezeCallStack #-}
203
204
205 -- | A single location in the source code.
206 --
207 -- @since 4.8.1.0
208 data SrcLoc = SrcLoc
209 { srcLocPackage :: [Char]
210 , srcLocModule :: [Char]
211 , srcLocFile :: [Char]
212 , srcLocStartLine :: Int
213 , srcLocStartCol :: Int
214 , srcLocEndLine :: Int
215 , srcLocEndCol :: Int
216 } deriving Eq