The unpac monorepo manager self-hosting as a monorepo using unpac
Extend Printexc API for raw backtrace entries (#9663)
authored by
Stephen Dolan
and committed by
GitHub
523fba91
601819f9
+65
-20
+3
Changes
+3
Changes
···
129
129
(Bernhard Schommer, review by Daniel Bünzli, Gabriel Scherer and
130
130
Alain Frisch)
131
131
132
+
- #9663: Extend Printexc API for raw backtrace entries.
133
+
(Stephen Dolan, review by Nicolás Ojeda Bär and Gabriel Scherer)
134
+
132
135
### Other libraries:
133
136
134
137
* #9206, #9419: update documentation of the threads library;
+9
-4
stdlib/printexc.ml
+9
-4
stdlib/printexc.ml
···
92
92
exit 2
93
93
94
94
type raw_backtrace_slot
95
-
type raw_backtrace
95
+
type raw_backtrace_entry = private int
96
+
type raw_backtrace = raw_backtrace_entry array
97
+
98
+
let raw_backtrace_entries bt = bt
96
99
97
100
external get_raw_backtrace:
98
101
unit -> raw_backtrace = "caml_get_exception_raw_backtrace"
···
234
237
then Some backtrace
235
238
else None
236
239
240
+
let backtrace_slots_of_raw_entry entry =
241
+
backtrace_slots [| entry |]
242
+
237
243
module Slot = struct
238
244
type t = backtrace_slot
239
245
let format = format_backtrace_slot
···
243
249
let name = backtrace_slot_defname
244
250
end
245
251
246
-
external raw_backtrace_length :
247
-
raw_backtrace -> int = "caml_raw_backtrace_length" [@@noalloc]
252
+
let raw_backtrace_length bt = Array.length bt
248
253
249
254
external get_raw_backtrace_slot :
250
255
raw_backtrace -> int -> raw_backtrace_slot = "caml_raw_backtrace_slot"
···
289
294
290
295
let set_uncaught_exception_handler fn = uncaught_exception_handler := fn
291
296
292
-
let empty_backtrace : raw_backtrace = Obj.obj (Obj.new_block Obj.abstract_tag 0)
297
+
let empty_backtrace : raw_backtrace = [| |]
293
298
294
299
let try_get_raw_backtrace () =
295
300
try
+53
-16
stdlib/printexc.mli
+53
-16
stdlib/printexc.mli
···
110
110
(** {1 Raw backtraces} *)
111
111
112
112
type raw_backtrace
113
-
(** The abstract type [raw_backtrace] stores a backtrace in
114
-
a low-level format, instead of directly exposing them as string as
115
-
the [get_backtrace()] function does.
113
+
(** The type [raw_backtrace] stores a backtrace in a low-level format,
114
+
which can be converted to usable form using [raw_backtrace_entries]
115
+
and [backtrace_slots_of_raw_entry] below.
116
116
117
-
This allows delaying the formatting of backtraces to when they are
118
-
actually printed, which may be useful if you record more
119
-
backtraces than you print.
117
+
Converting backtraces to [backtrace_slot]s is slower than capturing the
118
+
backtraces. If an application processes many backtraces, it can be useful
119
+
to use [raw_backtrace] to avoid or delay conversion.
120
120
121
121
Raw backtraces cannot be marshalled. If you need marshalling, you
122
122
should use the array returned by the [backtrace_slots] function of
···
125
125
@since 4.01.0
126
126
*)
127
127
128
+
type raw_backtrace_entry = private int
129
+
(** A [raw_backtrace_entry] is an element of a [raw_backtrace].
130
+
131
+
Each [raw_backtrace_entry] is an opaque integer, whose value is not stable
132
+
between different programs, or even between different runs of the same
133
+
binary.
134
+
135
+
A [raw_backtrace_entry] can be converted to a usable form using
136
+
[backtrace_slots_of_raw_entry] below. Note that, due to inlining, a
137
+
single [raw_backtrace_entry] may convert to several [backtrace_slot]s.
138
+
Since the values of a [raw_backtrace_entry] are not stable, they cannot
139
+
be marshalled. If they are to be converted, the conversion must be done
140
+
by the process that generated them.
141
+
142
+
Again due to inlining, there may be multiple distinct raw_backtrace_entry
143
+
values that convert to equal [backtrace_slot]s. However, if two
144
+
[raw_backtrace_entry]s are equal as integers, then they represent the same
145
+
[backtrace_slot]s.
146
+
147
+
@since 4.12.0 *)
148
+
149
+
val raw_backtrace_entries : raw_backtrace -> raw_backtrace_entry array
150
+
(** @since 4.12.0 *)
151
+
128
152
val get_raw_backtrace: unit -> raw_backtrace
129
153
(** [Printexc.get_raw_backtrace ()] returns the same exception
130
154
backtrace that [Printexc.print_backtrace] would print, but in
···
224
248
@since 4.02.0
225
249
*)
226
250
251
+
val backtrace_slots_of_raw_entry :
252
+
raw_backtrace_entry -> backtrace_slot array option
253
+
(** Returns the slots of a single raw backtrace entry, or [None] if this
254
+
entry lacks debug information.
255
+
256
+
Slots are returned in the same order as [backtrace_slots]: the slot
257
+
at index [0] is the most recent call, raise, or primitive, and
258
+
subsequent slots represent callers.
259
+
260
+
@since 4.12
261
+
*)
262
+
263
+
227
264
type location = {
228
265
filename : string;
229
266
line_number : int;
···
296
333
(** {1 Raw backtrace slots} *)
297
334
298
335
type raw_backtrace_slot
299
-
(** This type allows direct access to raw backtrace slots, without any
300
-
conversion in an OCaml-usable data-structure. Being
301
-
process-specific, they must absolutely not be marshalled, and are
302
-
unsafe to use for this reason (marshalling them may not fail, but
303
-
un-marshalling and using the result will result in
304
-
undefined behavior).
336
+
(** This type is used to iterate over the slots of a [raw_backtrace].
337
+
For most purposes, [backtrace_slots_of_raw_entry] is easier to use.
305
338
306
-
Elements of this type can still be compared and hashed: when two
307
-
elements are equal, then they represent the same source location
308
-
(the converse is not necessarily true in presence of inlining,
309
-
for example).
339
+
Like [raw_backtrace_entry], values of this type are process-specific and
340
+
must absolutely not be marshalled, and are unsafe to use for this reason
341
+
(marshalling them may not fail, but un-marshalling and using the result
342
+
will result in undefined behavior).
343
+
344
+
Elements of this type can still be compared and hashed: when two elements
345
+
are equal, then they represent the same source location (the converse is not
346
+
necessarily true in presence of inlining, for example).
310
347
311
348
@since 4.02.0
312
349
*)