gh-111997: C-API for signalling monitoring events

Include/internal/pycore_instruments.h

@@ -101,6 +101,89 @@ _Py_Instrumentation_GetLine(PyCodeObject *code, int index);
 extern PyObject _PyInstrumentation_MISSING;
 extern PyObject _PyInstrumentation_DISABLE;
 
+typedef struct _PyMonitoringState {
+    uint8_t active;
+    uint8_t opaque;
+} PyMonitoringState;
+
+
+/*** C API ***/
+
+PyAPI_FUNC(void)
+_PyMonitoringScopeBegin(PyMonitoringState *state_array, uint64_t *version,
+                        uint8_t *event_types, uint32_t length);
+
+PyAPI_FUNC(int)
+_PyMonitoring_FirePyStartEvent(PyMonitoringState *state, PyObject *codelike, uint32_t offset);
+
+PyAPI_FUNC(int)
+_PyMonitoring_FirePyResumeEvent(PyMonitoringState *state, PyObject *codelike, uint32_t offset);
+
+PyAPI_FUNC(int)
+_PyMonitoring_FirePyReturnEvent(PyMonitoringState *state, PyObject *codelike, uint32_t offset,
+                                PyObject *retval);
+
+PyAPI_FUNC(int)
+_PyMonitoring_FirePyYieldEvent(PyMonitoringState *state, PyObject *codelike, uint32_t offset,
+                               PyObject *retval);
+
+PyAPI_FUNC(int)
+_PyMonitoring_FirePyCallEvent(PyMonitoringState *state, PyObject *codelike, uint32_t offset,
+                              PyObject* callable, PyObject *arg0);
+
+PyAPI_FUNC(int)
+_PyMonitoring_FireCallEvent(PyMonitoringState *state, PyObject *codelike, uint32_t offset,
+                            PyObject* callable, PyObject *arg0);
+
+
+PyAPI_FUNC(int)
+_PyMonitoring_FireLineEvent(PyMonitoringState *state, PyObject *codelike, uint32_t offset,
+                            PyObject *lineno);
+
+PyAPI_FUNC(int)
+_PyMonitoring_FireInstructionEvent(PyMonitoringState *state, PyObject *codelike, uint32_t offset);
+
+PyAPI_FUNC(int)
+_PyMonitoring_FireJumpEvent(PyMonitoringState *state, PyObject *codelike, uint32_t offset,
+                            PyObject *target_offset);
+
+PyAPI_FUNC(int)
+_PyMonitoring_FireBranchEvent(PyMonitoringState *state, PyObject *codelike, uint32_t offset,
+                              PyObject *target_offset);
+
+PyAPI_FUNC(int)
+_PyMonitoring_FireCReturnEvent(PyMonitoringState *state, PyObject *codelike, uint32_t offset,
+                               PyObject *callable, PyObject *arg0);
+
+PyAPI_FUNC(int)
+_PyMonitoring_FirePyThrowEvent(PyMonitoringState *state, PyObject *codelike, uint32_t offset,
+                               PyObject *exception);
+
+
+PyAPI_FUNC(int)
+_PyMonitoring_FireRaiseEvent(PyMonitoringState *state, PyObject *codelike, uint32_t offset,
+                             PyObject *exception);
+
+PyAPI_FUNC(int)
+_PyMonitoring_FireReraiseEvent(PyMonitoringState *state, PyObject *codelike, uint32_t offset,
+                               PyObject *exception);
+
+PyAPI_FUNC(int)
+_PyMonitoring_FireExceptionHandledEvent(PyMonitoringState *state, PyObject *codelike, uint32_t offset,
+                                        PyObject *exception);
+
+PyAPI_FUNC(int)
+_PyMonitoring_FireCRaiseEvent(PyMonitoringState *state, PyObject *codelike, uint32_t offset,
+                              PyObject *callable, PyObject *arg0);
+
+PyAPI_FUNC(int)
+_PyMonitoring_FirePyUnwindEvent(PyMonitoringState *state, PyObject *codelike, uint32_t offset,
+                                PyObject *exception);
+
+PyAPI_FUNC(int)
+_PyMonitoring_FireStopIterationEvent(PyMonitoringState *state, PyObject *codelike, uint32_t offset,
+                                     PyObject *exception);
+
 #ifdef __cplusplus
 }
 #endif

Lib/test/test_monitoring.py

@@ -9,6 +9,8 @@
 import types
 import unittest
 import asyncio
+import _testinternalcapi
+
 from test import support
 from test.support import requires_specialization, script_helper
 
@@ -1868,3 +1870,132 @@ def test_monitoring_live_at_shutdown(self):
         # instrumentation code.
         script = support.findfile("_test_monitoring_shutdown.py")
         script_helper.run_test_script(script)
+
+
+class TestCApiEventGeneration(MonitoringTestBase, unittest.TestCase):
+
+    def setUp(self):
+        super(TestCApiEventGeneration, self).setUp()
+
+        self.codelike = _testinternalcapi.CodeLike(2)
+
+        def cb(name, args):
+            self.results.append((name,) + args)
+
+        self.cb1 = lambda codelike, *args : cb('cb1', args)
+        self.cb2 = lambda codelike, *args : cb('cb2', args)
+        self.cb3 = lambda codelike, *args : cb('cb3', args)
+
+        events = sys.monitoring.events
+        capi = _testinternalcapi
+        self.cases = [
+            # (Event, function, *args)
+            (events.PY_START, capi.fire_event_py_start),
+            (events.PY_RESUME, capi.fire_event_py_resume),
+            (events.PY_RETURN, capi.fire_event_py_return, 10),
+            (events.PY_YIELD, capi.fire_event_py_yield, 20),
+            (events.CALL, capi.fire_event_call, callable, 30),
+            (events.LINE, capi.fire_event_line, 40),
+            (events.JUMP, capi.fire_event_jump, 50),
+            (events.BRANCH, capi.fire_event_branch, 60),
+            (events.PY_THROW, capi.fire_event_py_throw, ValueError(1)),
+            (events.RAISE, capi.fire_event_raise, ValueError(2)),
+            (events.RERAISE, capi.fire_event_reraise, ValueError(3)),
+            (events.EXCEPTION_HANDLED, capi.fire_event_exception_handled, ValueError(4)),
+            (events.PY_UNWIND, capi.fire_event_py_unwind, ValueError(5)),
+            (events.STOP_ITERATION, capi.fire_event_stop_iteration, ValueError(6)),
+        ]
+
+    def test_fire_event(self):
+        for event, function, *args in self.cases:
+            offset = 0
+            self.codelike = _testinternalcapi.CodeLike(2)
+            with self.subTest(event):
+                output = (offset, *args)
+                # Register TEST_TOOL and TEST_TOOL2, but activate only TEST_TOOL
+                sys.monitoring.register_callback(TEST_TOOL, event, self.cb1)
+                sys.monitoring.register_callback(TEST_TOOL2, event, self.cb2)
+                active = 1 << TEST_TOOL
+
+                try:
+                    self.results = []
+                    # fire one of each event type
+                    for _, function, *args in self.cases:
+                        res = function(self.codelike, offset, active, *args)
+                        try:
+                          self.assertEqual(res, active)
+                        except:
+                          breakpoint()
+                          raise
+
+                    self.assertEqual(self.results, [('cb1',) + output])
+                finally:
+                    sys.monitoring.register_callback(TEST_TOOL, event, None)
+                    sys.monitoring.register_callback(TEST_TOOL2, event, None)
+
+    def test_disable_event(self):
+        events = sys.monitoring.events
+        cannot_disable = { events.PY_THROW, events.RAISE, events.RERAISE,
+                           events.EXCEPTION_HANDLED, events.PY_UNWIND }
+
+        def cb_disable(*args):
+            self.cb1(*args)
+            return sys.monitoring.DISABLE
+
+        for event, function, *args in self.cases:
+            offset = 1
+            self.codelike = _testinternalcapi.CodeLike(2)
+            with self.subTest(function.__name__):
+                output = (offset, *args)
+
+                sys.monitoring.register_callback(TEST_TOOL, event, cb_disable)
+                active = 1 << TEST_TOOL
+
+                try:
+                    # fire one of each event type
+                    self.results = []
+                    for f_event, function, *args in self.cases:
+                        if f_event == event and f_event in cannot_disable:
+                            with self.assertRaises(ValueError):
+                                res = function(self.codelike, offset, active, *args)
+                            try:
+                              self.assertEqual(res, active)
+                            except:
+                              breakpoint()
+                              raise
+                        else:
+                            res = function(self.codelike, offset, active, *args)
+                            self.assertEqual(res, 0 if f_event == event else active)
+                    self.assertEqual(self.results, [('cb1',) + output])
+
+                finally:
+                    sys.monitoring.register_callback(TEST_TOOL, event, None)
+                    sys.monitoring.register_callback(TEST_TOOL2, event, None)
+
+    def test_enter_scope(self):
+        events = sys.monitoring.events
+        capi = _testinternalcapi
+
+        cl = _testinternalcapi.CodeLike(2)
+        capi.enter_scope_py_start_py_return(cl)    # events = [PY_START, PY_RETURN]
+
+        sys.monitoring.register_callback(sys.monitoring.PROFILER_ID, events.PY_START, self.cb1)
+
+        self.results = []
+        capi.fire_event_py_start(cl, 0, 1 << sys.monitoring.PROFILER_ID)
+        capi.fire_event_py_return(cl, 1, 1 << sys.monitoring.PROFILER_ID, 42)
+        self.assertEqual(self.results, [('cb1', 0)])
+
+        sys.monitoring.register_callback(sys.monitoring.PROFILER_ID, events.PY_RETURN, self.cb2)
+
+        self.results = []
+        capi.fire_event_py_start(cl, 0, 1 << sys.monitoring.PROFILER_ID)
+        capi.fire_event_py_return(cl, 1, 1 << sys.monitoring.PROFILER_ID, 42)
+        self.assertEqual(self.results, [('cb1', 0), ('cb2', 1, 42)])
+
+        sys.monitoring.register_callback(sys.monitoring.PROFILER_ID, events.PY_START, None)
+
+        self.results = []
+        capi.fire_event_py_start(cl, 0, 1 << sys.monitoring.PROFILER_ID)
+        capi.fire_event_py_return(cl, 1, 1 << sys.monitoring.PROFILER_ID, 42)
+        self.assertEqual(self.results, [('cb2', 1, 42)])

Modules/Setup.stdlib.in

@@ -161,7 +161,7 @@
 @MODULE_XXSUBTYPE_TRUE@xxsubtype xxsubtype.c
 @MODULE__XXTESTFUZZ_TRUE@_xxtestfuzz _xxtestfuzz/_xxtestfuzz.c _xxtestfuzz/fuzzer.c
 @MODULE__TESTBUFFER_TRUE@_testbuffer _testbuffer.c
-@MODULE__TESTINTERNALCAPI_TRUE@_testinternalcapi _testinternalcapi.c _testinternalcapi/test_lock.c _testinternalcapi/pytime.c _testinternalcapi/set.c _testinternalcapi/test_critical_sections.c
+@MODULE__TESTINTERNALCAPI_TRUE@_testinternalcapi _testinternalcapi.c _testinternalcapi/test_lock.c _testinternalcapi/pytime.c _testinternalcapi/set.c _testinternalcapi/test_critical_sections.c _testinternalcapi/monitoring.c
 @MODULE__TESTCAPI_TRUE@_testcapi _testcapimodule.c _testcapi/vectorcall.c _testcapi/vectorcall_limited.c _testcapi/heaptype.c _testcapi/abstract.c _testcapi/bytearray.c _testcapi/bytes.c _testcapi/unicode.c _testcapi/dict.c _testcapi/set.c _testcapi/list.c _testcapi/tuple.c _testcapi/getargs.c _testcapi/datetime.c _testcapi/docstring.c _testcapi/mem.c _testcapi/watchers.c _testcapi/long.c _testcapi/float.c _testcapi/complex.c _testcapi/numbers.c _testcapi/structmember.c _testcapi/exceptions.c _testcapi/code.c _testcapi/buffer.c _testcapi/pyatomic.c _testcapi/pyos.c _testcapi/file.c _testcapi/codec.c _testcapi/immortal.c _testcapi/heaptype_relative.c _testcapi/gc.c _testcapi/sys.c _testcapi/hash.c _testcapi/time.c
 @MODULE__TESTCLINIC_TRUE@_testclinic _testclinic.c
 @MODULE__TESTCLINIC_LIMITED_TRUE@_testclinic_limited _testclinic_limited.c

Modules/_testinternalcapi.c

@@ -1769,6 +1769,9 @@ module_exec(PyObject *module)
     if (_PyTestInternalCapi_Init_CriticalSection(module) < 0) {
         return 1;
     }
+    if (_PyTestInternalCapi_Init_Monitoring(module) < 0) {
+        return 1;
+    }
 
     Py_ssize_t sizeof_gc_head = 0;
 #ifndef Py_GIL_DISABLED