GH-103082: Implementation of PEP 669: Low Impact Monitoring for CPython (GH-103083)

* The majority of the monitoring code is in instrumentation.c
* The new instrumentation bytecodes are in bytecodes.c
* legacy_tracing.c adapts the new API to the old sys.setrace and sys.setprofile APIs

Author: markshannon

Include/cpython/code.h

@@ -3,10 +3,22 @@
 #ifndefPy_LIMITED_API
 #ifndefPy_CODE_H
 #definePy_CODE_H
+
 #ifdef__cplusplus
 extern"C" {
 #endif
 
+
+/* Count of all "real" monitoring events (not derived from other events) */
+#definePY_MONITORING_UNGROUPED_EVENTS 14
+/* Count of all monitoring events */
+#definePY_MONITORING_EVENTS 16
+
+/* Table of which tools are active for each monitored event. */
+typedefstruct_Py_Monitors {
+uint8_ttools[PY_MONITORING_UNGROUPED_EVENTS];
+} _Py_Monitors;
+
 /* Each instruction in a code object is a fixed-width value,
  * currently 2 bytes: 1-byte opcode + 1-byte oparg. The EXTENDED_ARG
  * opcode allows for larger values but the current limit is 3 uses
@@ -56,6 +68,35 @@ typedef struct {
 PyObject*_co_freevars;
 } _PyCoCached;
 
+/* Ancilliary data structure used for instrumentation.
+ Line instrumentation creates an array of
+ these. One entry per code unit.*/
+typedefstruct {
+uint8_toriginal_opcode;
+int8_tline_delta;
+} _PyCoLineInstrumentationData;
+
+/* Main data structure used for instrumentation.
+ * This is allocated when needed for instrumentation
+ */
+typedefstruct {
+/* Monitoring specific to this code object */
+_Py_Monitorslocal_monitors;
+/* Monitoring that is active on this code object */
+_Py_Monitorsactive_monitors;
+/* The tools that are to be notified for events for the matching code unit */
+uint8_t*tools;
+/* Information to support line events */
+_PyCoLineInstrumentationData*lines;
+/* The tools that are to be notified for line events for the matching code unit */
+uint8_t*line_tools;
+/* Information to support instruction events */
+/* The underlying instructions, which can themselves be instrumented */
+uint8_t*per_instruction_opcodes;
+/* The tools that are to be notified for instruction events for the matching code unit */
+uint8_t*per_instruction_tools;
+} _PyCoMonitoringData;
+
 // To avoid repeating ourselves in deepfreeze.py, all PyCodeObject members are
 // defined in this macro:
 #define_PyCode_DEF(SIZE) { \
@@ -87,7 +128,6 @@ typedef struct {
 PyObject*co_exceptiontable; /* Byte string encoding exception handling \
  table */ \
 intco_flags; /* CO_..., see below */ \
-short_co_linearray_entry_size; /* Size of each entry in _co_linearray */ \
  \
 /* The rest are not so impactful on performance. */ \
 intco_argcount; /* #arguments, except *args */ \
@@ -114,8 +154,9 @@ typedef struct {
 PyObject*co_linetable; /* bytes object that holds location info */ \
 PyObject*co_weakreflist; /* to support weakrefs to code objects */ \
 _PyCoCached*_co_cached; /* cached co_* attributes */ \
+uint64_t_co_instrumentation_version; /* current instrumentation version */ \
+_PyCoMonitoringData*_co_monitoring; /* Monitoring data */ \
 int_co_firsttraceable; /* index of first traceable instruction */ \
-char*_co_linearray; /* array of line offsets */ \
 /* Scratch space for extra data relating to the code object. \
  Type is a void* to keep the format private in codeobject.c to force \
  people to go through the proper APIs. */ \

Include/cpython/pystate.h

@@ -58,12 +58,6 @@ typedef int (*Py_tracefunc)(PyObject *, PyFrameObject *, int, PyObject *);
 #definePyTrace_C_RETURN 6
 #definePyTrace_OPCODE 7
 
-
-typedefstruct {
-PyCodeObject*code; // The code object for the bounds. May be NULL.
-PyCodeAddressRangebounds; // Only valid if code != NULL.
-} PyTraceInfo;
-
 // Internal structure: you should not use it directly, but use public functions
 // like PyThreadState_EnterTracing() and PyThreadState_LeaveTracing().
 typedefstruct_PyCFrame {
@@ -77,7 +71,6 @@ typedef struct _PyCFrame {
  * discipline and make sure that instances of this struct cannot
  * accessed outside of their lifetime.
  */
-uint8_tuse_tracing; // 0 or 255 (or'ed into opcode, hence 8-bit type)
 /* Pointer to the currently executing frame (it can be NULL) */
 struct_PyInterpreterFrame*current_frame;
 struct_PyCFrame*previous;
@@ -157,7 +150,7 @@ struct _ts {
  This is to prevent the actual trace/profile code from being recorded in
  the trace/profile. */
 inttracing;
-inttracing_what; /* The event currently being traced, if any. */
+intwhat_event; /* The event currently being monitored, if any. */
 
 /* Pointer to current _PyCFrame in the C stack frame of the currently,
  * or most recently, executing _PyEval_EvalFrameDefault. */
@@ -228,8 +221,6 @@ struct _ts {
 /* Unique thread state id. */
 uint64_tid;
 
-PyTraceInfotrace_info;
-
 _PyStackChunk*datastack_chunk;
 PyObject**datastack_top;
 PyObject**datastack_limit;

Include/internal/pycore_code.h

@@ -441,32 +441,6 @@ adaptive_counter_backoff(uint16_t counter) {
 
 /* Line array cache for tracing */
 
-externint_PyCode_CreateLineArray(PyCodeObject*co);
-
-staticinlineint
-_PyCode_InitLineArray(PyCodeObject*co)
-{
-if (co->_co_linearray) {
-return0;
- }
-return_PyCode_CreateLineArray(co);
-}
-
-staticinlineint
-_PyCode_LineNumberFromArray(PyCodeObject*co, intindex)
-{
-assert(co->_co_linearray!=NULL);
-assert(index >= 0);
-assert(index<Py_SIZE(co));
-if (co->_co_linearray_entry_size==2) {
-return ((int16_t*)co->_co_linearray)[index];
- }
-else {
-assert(co->_co_linearray_entry_size==4);
-return ((int32_t*)co->_co_linearray)[index];
- }
-}
-
 typedefstruct_PyShimCodeDef {
 constuint8_t*code;
 intcodelen;
@@ -500,6 +474,10 @@ extern uint32_t _Py_next_func_version;
 
 #defineCOMPARISON_NOT_EQUALS (COMPARISON_UNORDERED | COMPARISON_LESS_THAN | COMPARISON_GREATER_THAN)
 
+externint_Py_Instrument(PyCodeObject*co, PyInterpreterState*interp);
+
+externint_Py_GetBaseOpcode(PyCodeObject*code, intoffset);
+
 
 #ifdef__cplusplus
 }

Include/internal/pycore_frame.h

@@ -19,6 +19,7 @@ struct _frame {
 struct_PyInterpreterFrame*f_frame; /* points to the frame data */
 PyObject*f_trace; /* Trace function */
 intf_lineno; /* Current line number. Only valid if non-zero */
+intf_last_traced_line; /* The last line traced for this frame */
 charf_trace_lines; /* Emit per-line trace events? */
 charf_trace_opcodes; /* Emit per-opcode trace events? */
 charf_fast_as_locals; /* Have the fast locals of this frame been converted to a dict? */
@@ -137,10 +138,16 @@ _PyFrame_GetLocalsArray(_PyInterpreterFrame *frame)
 returnframe->localsplus;
 }
 
+/* Fetches the stack pointer, and sets stacktop to -1.
+ Having stacktop <= 0 ensures that invalid
+ values are not visible to the cycle GC.
+ We choose -1 rather than 0 to assist debugging. */
 staticinlinePyObject**
 _PyFrame_GetStackPointer(_PyInterpreterFrame*frame)
 {
-returnframe->localsplus+frame->stacktop;
+PyObject**sp=frame->localsplus+frame->stacktop;
+frame->stacktop=-1;
+returnsp;
 }
 
 staticinlinevoid

Include/internal/pycore_instruments.h

@@ -0,0 +1,107 @@
+
+#ifndefPy_INTERNAL_INSTRUMENT_H
+#definePy_INTERNAL_INSTRUMENT_H
+
+
+#include"pycore_bitutils.h"// _Py_popcount32
+#include"pycore_frame.h"
+
+#include"cpython/code.h"
+
+#ifdef__cplusplus
+extern"C" {
+#endif
+
+#definePY_MONITORING_TOOL_IDS 8
+
+/* Local events.
+ * These require bytecode instrumentation */
+
+#definePY_MONITORING_EVENT_PY_START 0
+#definePY_MONITORING_EVENT_PY_RESUME 1
+#definePY_MONITORING_EVENT_PY_RETURN 2
+#definePY_MONITORING_EVENT_PY_YIELD 3
+#definePY_MONITORING_EVENT_CALL 4
+#definePY_MONITORING_EVENT_LINE 5
+#definePY_MONITORING_EVENT_INSTRUCTION 6
+#definePY_MONITORING_EVENT_JUMP 7
+#definePY_MONITORING_EVENT_BRANCH 8
+#definePY_MONITORING_EVENT_STOP_ITERATION 9
+
+#definePY_MONITORING_INSTRUMENTED_EVENTS 10
+
+/* Other events, mainly exceptions */
+
+#definePY_MONITORING_EVENT_RAISE 10
+#definePY_MONITORING_EVENT_EXCEPTION_HANDLED 11
+#definePY_MONITORING_EVENT_PY_UNWIND 12
+#definePY_MONITORING_EVENT_PY_THROW 13
+
+
+/* Ancilliary events */
+
+#definePY_MONITORING_EVENT_C_RETURN 14
+#definePY_MONITORING_EVENT_C_RAISE 15
+
+
+typedefuint32_t_PyMonitoringEventSet;
+
+/* Tool IDs */
+
+/* These are defined in PEP 669 for convenience to avoid clashes */
+#definePY_MONITORING_DEBUGGER_ID 0
+#definePY_MONITORING_COVERAGE_ID 1
+#definePY_MONITORING_PROFILER_ID 2
+#definePY_MONITORING_OPTIMIZER_ID 5
+
+/* Internal IDs used to suuport sys.setprofile() and sys.settrace() */
+#definePY_MONITORING_SYS_PROFILE_ID 6
+#definePY_MONITORING_SYS_TRACE_ID 7
+
+
+PyObject*_PyMonitoring_RegisterCallback(inttool_id, intevent_id, PyObject*obj);
+
+int_PyMonitoring_SetEvents(inttool_id, _PyMonitoringEventSetevents);
+
+externint
+_Py_call_instrumentation(PyThreadState*tstate, intevent,
+_PyInterpreterFrame*frame, _Py_CODEUNIT*instr);
+
+externint
+_Py_call_instrumentation_line(PyThreadState*tstate, _PyInterpreterFrame*frame,
+_Py_CODEUNIT*instr);
+
+externint
+_Py_call_instrumentation_instruction(
+PyThreadState*tstate, _PyInterpreterFrame*frame, _Py_CODEUNIT*instr);
+
+int
+_Py_call_instrumentation_jump(
+PyThreadState*tstate, intevent,
+_PyInterpreterFrame*frame, _Py_CODEUNIT*instr, _Py_CODEUNIT*target);
+
+externint
+_Py_call_instrumentation_arg(PyThreadState*tstate, intevent,
+_PyInterpreterFrame*frame, _Py_CODEUNIT*instr, PyObject*arg);
+
+externint
+_Py_call_instrumentation_2args(PyThreadState*tstate, intevent,
+_PyInterpreterFrame*frame, _Py_CODEUNIT*instr, PyObject*arg0, PyObject*arg1);
+
+externvoid
+_Py_call_instrumentation_exc0(PyThreadState*tstate, intevent,
+_PyInterpreterFrame*frame, _Py_CODEUNIT*instr);
+
+externvoid
+_Py_call_instrumentation_exc2(PyThreadState*tstate, intevent,
+_PyInterpreterFrame*frame, _Py_CODEUNIT*instr, PyObject*arg0, PyObject*arg1);
+
+externint
+_Py_Instrumentation_GetLine(PyCodeObject*code, intindex);
+
+externPyObject_PyInstrumentation_MISSING;
+
+#ifdef__cplusplus
+}
+#endif
+#endif/* !Py_INTERNAL_INSTRUMENT_H */

Include/internal/pycore_interp.h

@@ -24,6 +24,7 @@ extern "C" {
 #include"pycore_genobject.h"// struct _Py_async_gen_state
 #include"pycore_gc.h"// struct _gc_runtime_state
 #include"pycore_import.h"// struct _import_state
+#include"pycore_instruments.h"// PY_MONITORING_EVENTS
 #include"pycore_list.h"// struct _Py_list_state
 #include"pycore_global_objects.h"// struct _Py_interp_static_objects
 #include"pycore_object_state.h"// struct _py_object_state
@@ -37,7 +38,6 @@ struct _Py_long_state {
 intmax_str_digits;
 };
 
-
 /* interpreter state */
 
 /* PyInterpreterState holds the global state for one of the runtime's
@@ -49,6 +49,9 @@ struct _is {
 
 PyInterpreterState*next;
 
+uint64_tmonitoring_version;
+uint64_tlast_restart_version;
+
 structpythreads {
 uint64_tnext_unique_id;
 /* The linked list of threads, newest first. */
@@ -148,6 +151,15 @@ struct _is {
 structcallable_cachecallable_cache;
 PyCodeObject*interpreter_trampoline;
 
+_Py_Monitorsmonitors;
+boolf_opcode_trace_set;
+boolsys_profile_initialized;
+boolsys_trace_initialized;
+Py_ssize_tsys_profiling_threads; /* Count of threads with c_profilefunc set */
+Py_ssize_tsys_tracing_threads; /* Count of threads with c_tracefunc set */
+PyObject*monitoring_callables[PY_MONITORING_TOOL_IDS][PY_MONITORING_EVENTS];
+PyObject*monitoring_tool_names[PY_MONITORING_TOOL_IDS];
+
 struct_Py_interp_cached_objectscached_objects;
 struct_Py_interp_static_objectsstatic_objects;