python3.13/cpython/monitoring.h

0001 #ifndef Py_CPYTHON_MONITORING_H
0002 #  error "this header file must not be included directly"
0003 #endif
0004
0005 /* Local events.
0006  * These require bytecode instrumentation */
0007
0008 #define PY_MONITORING_EVENT_PY_START 0
0009 #define PY_MONITORING_EVENT_PY_RESUME 1
0010 #define PY_MONITORING_EVENT_PY_RETURN 2
0011 #define PY_MONITORING_EVENT_PY_YIELD 3
0012 #define PY_MONITORING_EVENT_CALL 4
0013 #define PY_MONITORING_EVENT_LINE 5
0014 #define PY_MONITORING_EVENT_INSTRUCTION 6
0015 #define PY_MONITORING_EVENT_JUMP 7
0016 #define PY_MONITORING_EVENT_BRANCH 8
0017 #define PY_MONITORING_EVENT_STOP_ITERATION 9
0018
0019 #define PY_MONITORING_IS_INSTRUMENTED_EVENT(ev) \
0020     ((ev) < _PY_MONITORING_LOCAL_EVENTS)
0021
0022 /* Other events, mainly exceptions */
0023
0024 #define PY_MONITORING_EVENT_RAISE 10
0025 #define PY_MONITORING_EVENT_EXCEPTION_HANDLED 11
0026 #define PY_MONITORING_EVENT_PY_UNWIND 12
0027 #define PY_MONITORING_EVENT_PY_THROW 13
0028 #define PY_MONITORING_EVENT_RERAISE 14
0029
0030
0031 /* Ancillary events */
0032
0033 #define PY_MONITORING_EVENT_C_RETURN 15
0034 #define PY_MONITORING_EVENT_C_RAISE 16
0035
0036
0037 typedef struct _PyMonitoringState {
0038     uint8_t active;
0039     uint8_t opaque;
0040 } PyMonitoringState;
0041
0042
0043 PyAPI_FUNC(int)
0044 PyMonitoring_EnterScope(PyMonitoringState *state_array, uint64_t *version,
0045                          const uint8_t *event_types, Py_ssize_t length);
0046
0047 PyAPI_FUNC(int)
0048 PyMonitoring_ExitScope(void);
0049
0050
0051 PyAPI_FUNC(int)
0052 _PyMonitoring_FirePyStartEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset);
0053
0054 PyAPI_FUNC(int)
0055 _PyMonitoring_FirePyResumeEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset);
0056
0057 PyAPI_FUNC(int)
0058 _PyMonitoring_FirePyReturnEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset,
0059                                 PyObject *retval);
0060
0061 PyAPI_FUNC(int)
0062 _PyMonitoring_FirePyYieldEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset,
0063                                PyObject *retval);
0064
0065 PyAPI_FUNC(int)
0066 _PyMonitoring_FireCallEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset,
0067                             PyObject* callable, PyObject *arg0);
0068
0069 PyAPI_FUNC(int)
0070 _PyMonitoring_FireLineEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset,
0071                             int lineno);
0072
0073 PyAPI_FUNC(int)
0074 _PyMonitoring_FireJumpEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset,
0075                             PyObject *target_offset);
0076
0077 PyAPI_FUNC(int)
0078 _PyMonitoring_FireBranchEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset,
0079                               PyObject *target_offset);
0080
0081 PyAPI_FUNC(int)
0082 _PyMonitoring_FireCReturnEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset,
0083                                PyObject *retval);
0084
0085 PyAPI_FUNC(int)
0086 _PyMonitoring_FirePyThrowEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset);
0087
0088 PyAPI_FUNC(int)
0089 _PyMonitoring_FireRaiseEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset);
0090
0091 PyAPI_FUNC(int)
0092 _PyMonitoring_FireReraiseEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset);
0093
0094 PyAPI_FUNC(int)
0095 _PyMonitoring_FireExceptionHandledEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset);
0096
0097 PyAPI_FUNC(int)
0098 _PyMonitoring_FireCRaiseEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset);
0099
0100 PyAPI_FUNC(int)
0101 _PyMonitoring_FirePyUnwindEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset);
0102
0103 PyAPI_FUNC(int)
0104 _PyMonitoring_FireStopIterationEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset, PyObject *value);
0105
0106
0107 #define _PYMONITORING_IF_ACTIVE(STATE, X)  \
0108     if ((STATE)->active) { \
0109         return (X); \
0110     } \
0111     else { \
0112         return 0; \
0113     }
0114
0115 static inline int
0116 PyMonitoring_FirePyStartEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset)
0117 {
0118     _PYMONITORING_IF_ACTIVE(
0119         state,
0120         _PyMonitoring_FirePyStartEvent(state, codelike, offset));
0121 }
0122
0123 static inline int
0124 PyMonitoring_FirePyResumeEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset)
0125 {
0126     _PYMONITORING_IF_ACTIVE(
0127         state,
0128         _PyMonitoring_FirePyResumeEvent(state, codelike, offset));
0129 }
0130
0131 static inline int
0132 PyMonitoring_FirePyReturnEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset,
0133                                PyObject *retval)
0134 {
0135     _PYMONITORING_IF_ACTIVE(
0136         state,
0137         _PyMonitoring_FirePyReturnEvent(state, codelike, offset, retval));
0138 }
0139
0140 static inline int
0141 PyMonitoring_FirePyYieldEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset,
0142                               PyObject *retval)
0143 {
0144     _PYMONITORING_IF_ACTIVE(
0145         state,
0146         _PyMonitoring_FirePyYieldEvent(state, codelike, offset, retval));
0147 }
0148
0149 static inline int
0150 PyMonitoring_FireCallEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset,
0151                            PyObject* callable, PyObject *arg0)
0152 {
0153     _PYMONITORING_IF_ACTIVE(
0154         state,
0155         _PyMonitoring_FireCallEvent(state, codelike, offset, callable, arg0));
0156 }
0157
0158 static inline int
0159 PyMonitoring_FireLineEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset,
0160                            int lineno)
0161 {
0162     _PYMONITORING_IF_ACTIVE(
0163         state,
0164         _PyMonitoring_FireLineEvent(state, codelike, offset, lineno));
0165 }
0166
0167 static inline int
0168 PyMonitoring_FireJumpEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset,
0169                            PyObject *target_offset)
0170 {
0171     _PYMONITORING_IF_ACTIVE(
0172         state,
0173         _PyMonitoring_FireJumpEvent(state, codelike, offset, target_offset));
0174 }
0175
0176 static inline int
0177 PyMonitoring_FireBranchEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset,
0178                              PyObject *target_offset)
0179 {
0180     _PYMONITORING_IF_ACTIVE(
0181         state,
0182         _PyMonitoring_FireBranchEvent(state, codelike, offset, target_offset));
0183 }
0184
0185 static inline int
0186 PyMonitoring_FireCReturnEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset,
0187                               PyObject *retval)
0188 {
0189     _PYMONITORING_IF_ACTIVE(
0190         state,
0191         _PyMonitoring_FireCReturnEvent(state, codelike, offset, retval));
0192 }
0193
0194 static inline int
0195 PyMonitoring_FirePyThrowEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset)
0196 {
0197     _PYMONITORING_IF_ACTIVE(
0198         state,
0199         _PyMonitoring_FirePyThrowEvent(state, codelike, offset));
0200 }
0201
0202 static inline int
0203 PyMonitoring_FireRaiseEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset)
0204 {
0205     _PYMONITORING_IF_ACTIVE(
0206         state,
0207         _PyMonitoring_FireRaiseEvent(state, codelike, offset));
0208 }
0209
0210 static inline int
0211 PyMonitoring_FireReraiseEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset)
0212 {
0213     _PYMONITORING_IF_ACTIVE(
0214         state,
0215         _PyMonitoring_FireReraiseEvent(state, codelike, offset));
0216 }
0217
0218 static inline int
0219 PyMonitoring_FireExceptionHandledEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset)
0220 {
0221     _PYMONITORING_IF_ACTIVE(
0222         state,
0223         _PyMonitoring_FireExceptionHandledEvent(state, codelike, offset));
0224 }
0225
0226 static inline int
0227 PyMonitoring_FireCRaiseEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset)
0228 {
0229     _PYMONITORING_IF_ACTIVE(
0230         state,
0231         _PyMonitoring_FireCRaiseEvent(state, codelike, offset));
0232 }
0233
0234 static inline int
0235 PyMonitoring_FirePyUnwindEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset)
0236 {
0237     _PYMONITORING_IF_ACTIVE(
0238         state,
0239         _PyMonitoring_FirePyUnwindEvent(state, codelike, offset));
0240 }
0241
0242 static inline int
0243 PyMonitoring_FireStopIterationEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset, PyObject *value)
0244 {
0245     _PYMONITORING_IF_ACTIVE(
0246         state,
0247         _PyMonitoring_FireStopIterationEvent(state, codelike, offset, value));
0248 }
0249
0250 #undef _PYMONITORING_IF_ACTIVE