Skip to content

Commit c9fbb72

Browse files
committed
Added implementation notes for [re]set_exc_info().
1 parent d6473d1 commit c9fbb72

1 file changed

Lines changed: 61 additions & 0 deletions

File tree

‎Python/ceval.c‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2616,6 +2616,67 @@ PyEval_EvalCodeEx(PyCodeObject *co, PyObject *globals, PyObject *locals,
26162616
}
26172617

26182618

2619+
/* Implementation notes for set_exc_info() and reset_exc_info():
2620+
2621+
- Below, 'exc_ZZZ' stands for 'exc_type', 'exc_value' and
2622+
'exc_traceback'. These always travel together.
2623+
2624+
- tstate->curexc_ZZZ is the "hot" exception that is set by
2625+
PyErr_SetString(), cleared by PyErr_Clear(), and so on.
2626+
2627+
- Once an exception is caught by an except clause, it is transferred
2628+
from tstate->curexc_ZZZ to tstate->exc_ZZZ, from which sys.exc_info()
2629+
can pick it up. This is the primary task of set_exc_info().
2630+
2631+
- Now let me explain the complicated dance with frame->f_exc_ZZZ.
2632+
2633+
Long ago, when none of this existed, there were just a few globals:
2634+
one set corresponding to the "hot" exception, and one set
2635+
corresponding to sys.exc_ZZZ. (Actually, the latter weren't C
2636+
globals; they were simply stored as sys.exc_ZZZ. For backwards
2637+
compatibility, they still are!) The problem was that in code like
2638+
this:
2639+
2640+
try:
2641+
"something that may fail"
2642+
except "some exception":
2643+
"do something else first"
2644+
"print the exception from sys.exc_ZZZ."
2645+
2646+
if "do something else first" invoked something that raised and caught
2647+
an exception, sys.exc_ZZZ were overwritten. That was a frequent
2648+
cause of subtle bugs. I fixed this by changing the semantics as
2649+
follows:
2650+
2651+
- Within one frame, sys.exc_ZZZ will hold the last exception caught
2652+
*in that frame*.
2653+
2654+
- But initially, and as long as no exception is caught in a given
2655+
frame, sys.exc_ZZZ will hold the last exception caught in the
2656+
previous frame (or the frame before that, etc.).
2657+
2658+
The first bullet fixed the bug in the above example. The second
2659+
bullet was for backwards compatibility: it was (and is) common to
2660+
have a function that is called when an exception is caught, and to
2661+
have that function access the caught exception via sys.exc_ZZZ.
2662+
(Example: traceback.print_exc()).
2663+
2664+
At the same time I fixed the problem that sys.exc_ZZZ weren't
2665+
thread-safe, by introducing sys.exc_info() which gets it from tstate;
2666+
but that's really a separate improvement.
2667+
2668+
The reset_exc_info() function in ceval.c restores the tstate->exc_ZZZ
2669+
variables to what they were before the current frame was called. The
2670+
set_exc_info() function saves them on the frame so that
2671+
reset_exc_info() can restore them. The invariant is that
2672+
frame->f_exc_ZZZ is NULL iff the current frame never caught an
2673+
exception (where "catching" an exception applies only to successful
2674+
except clauses); and if the current frame ever caught an exception,
2675+
frame->f_exc_ZZZ is the exception that was stored in tstate->exc_ZZZ
2676+
at the start of the current frame.
2677+
2678+
*/
2679+
26192680
static void
26202681
set_exc_info(PyThreadState *tstate,
26212682
PyObject *type, PyObject *value, PyObject *tb)

0 commit comments

Comments
 (0)