Мониторинг C API¶Monitoring C API

Добавлено в версии 3.13.

Расширению может потребоваться взаимодействие с системой мониторинга событий. Подписка на события и регистрация колбэков осуществляется через Python API, предоставленный в sys.monitoring.

Генерация событий выполнения¶Generating Execution Events

Приведённые ниже функции позволяют расширению генерировать события мониторинга при эмуляции выполнения кода Python. Каждая из этих функций принимает структуру PyMonitoringState, содержащую краткую информацию о состоянии активации событий, а также аргументы события, которые включают PyObject*, представляющий объект кода, смещение инструкции и иногда дополнительные аргументы, специфичные для события (см. sys.monitoring для подробностей о сигнатурах различных колбэков событий). Аргумент codelike должен быть экземпляром types.CodeType или типа, который его эмулирует.

ВМ отключает трассировку при генерации события, поэтому пользовательскому коду делать это не нужно.

Функции мониторинга не должны вызываться при установленном исключении, за исключением перечисленных ниже, которые работают с текущим исключением.

type PyMonitoringState¶: Представление состояния типа события. Выделяется пользователем, а его содержимое поддерживается функциями API мониторинга, описанными ниже.

Все приведённые ниже функции возвращают 0 при успехе и -1 (с установленным исключением) при ошибке.

Описания событий см. в sys.monitoring.

int PyMonitoring_FirePyStartEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset)¶: Генерирует событие PY_START.

int PyMonitoring_FirePyResumeEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset)¶: Генерирует событие PY_RESUME.

int PyMonitoring_FirePyReturnEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset, PyObject *retval)¶: Генерирует событие PY_RETURN.

int PyMonitoring_FirePyYieldEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset, PyObject *retval)¶: Генерирует событие PY_YIELD.

int PyMonitoring_FireCallEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset, PyObject *callable, PyObject *arg0)¶: Генерирует событие CALL.

int PyMonitoring_FireLineEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset, int lineno)¶: Генерирует событие LINE.

int PyMonitoring_FireJumpEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset, PyObject *target_offset)¶: Генерирует событие JUMP.

int PyMonitoring_FireBranchLeftEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset, PyObject *target_offset)¶: Генерирует событие BRANCH_LEFT.

int PyMonitoring_FireBranchRightEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset, PyObject *target_offset)¶: Генерирует событие BRANCH_RIGHT.

int PyMonitoring_FireCReturnEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset, PyObject *retval)¶: Генерирует событие C_RETURN.

int PyMonitoring_FirePyThrowEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset)¶: Генерирует событие PY_THROW с текущим исключением (как возвращено PyErr_GetRaisedException()).

int PyMonitoring_FireRaiseEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset)¶: Генерирует событие RAISE с текущим исключением (как возвращено PyErr_GetRaisedException()).

int PyMonitoring_FireCRaiseEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset)¶: Генерирует событие C_RAISE с текущим исключением (как возвращено PyErr_GetRaisedException()).

int PyMonitoring_FireReraiseEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset)¶: Генерирует событие RERAISE с текущим исключением (как возвращено PyErr_GetRaisedException()).

int PyMonitoring_FireExceptionHandledEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset)¶: Генерирует событие EXCEPTION_HANDLED с текущим исключением (как возвращено PyErr_GetRaisedException()).

int PyMonitoring_FirePyUnwindEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset)¶: Генерирует событие PY_UNWIND с текущим исключением (как возвращено PyErr_GetRaisedException()).

int PyMonitoring_FireStopIterationEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset, PyObject *value)¶: Генерирует событие STOP_ITERATION. Если value является экземпляром StopIteration, он используется. В противном случае создаётся новый экземпляр StopIteration с value в качестве аргумента.

Управление состоянием мониторинга¶Managing the Monitoring State

Состояниями мониторинга можно управлять с помощью областей мониторинга. Обычно область соответствует функции Python.

int PyMonitoring_EnterScope(PyMonitoringState *state_array, uint64_t *version, const uint8_t *event_types, Py_ssize_t length)¶

Входит в отслеживаемую область. event_types – это массив идентификаторов событий для событий, которые могут быть сгенерированы в этой области. Например, идентификатор события PY_START – это значение PY_MONITORING_EVENT_PY_START, численно равное двоичному логарифму sys.monitoring.events.PY_START. state_array – это массив с записью состояния мониторинга для каждого события в event_types; он выделяется пользователем, но заполняется PyMonitoring_EnterScope() информацией о состоянии активации события. Размер event_types (а следовательно, и state_array) задаётся в length.

Аргумент version – это указатель на значение, которое должно быть выделено пользователем вместе с state_array и инициализировано 0, а затем устанавливаться только самим PyMonitoring_EnterScope(). Это позволяет функции определять, изменились ли состояния событий с предыдущего вызова, и быстро возвращаться, если они не изменились.

Области, упомянутые здесь, – это лексические области: функция, класс или метод. PyMonitoring_EnterScope() должен вызываться при каждом входе в лексическую область. Области можно повторно входить, используя те же state_array и version, например, при эмуляции рекурсивной функции Python. Когда выполнение code-like приостанавливается, например, при эмуляции генератора, область нужно покинуть и войти снова.

Макросы для event_types:

Макрос	Событие
PY_MONITORING_EVENT_BRANCH_LEFT¶	`BRANCH_LEFT`
PY_MONITORING_EVENT_BRANCH_RIGHT¶	`BRANCH_RIGHT`
PY_MONITORING_EVENT_CALL¶	`CALL`
PY_MONITORING_EVENT_C_RAISE¶	`C_RAISE`
PY_MONITORING_EVENT_C_RETURN¶	`C_RETURN`
PY_MONITORING_EVENT_EXCEPTION_HANDLED¶	`EXCEPTION_HANDLED`
PY_MONITORING_EVENT_INSTRUCTION¶	`INSTRUCTION`
PY_MONITORING_EVENT_JUMP¶	`JUMP`
PY_MONITORING_EVENT_LINE¶	`LINE`
PY_MONITORING_EVENT_PY_RESUME¶	`PY_RESUME`
PY_MONITORING_EVENT_PY_RETURN¶	`PY_RETURN`
PY_MONITORING_EVENT_PY_START¶	`PY_START`
PY_MONITORING_EVENT_PY_THROW¶	`PY_THROW`
PY_MONITORING_EVENT_PY_UNWIND¶	`PY_UNWIND`
PY_MONITORING_EVENT_PY_YIELD¶	`PY_YIELD`
PY_MONITORING_EVENT_RAISE¶	`RAISE`
PY_MONITORING_EVENT_RERAISE¶	`RERAISE`
PY_MONITORING_EVENT_STOP_ITERATION¶	`STOP_ITERATION`

int PyMonitoring_ExitScope(void)¶: Завершает последнюю область видимости, открытую с помощью PyMonitoring_EnterScope().

int PY_MONITORING_IS_INSTRUMENTED_EVENT(uint8_t ev)¶: Возвращает true, если событие, соответствующее идентификатору события ev, является локальным событием.

Добавлено в версии 3.13.

Soft deprecated since version 3.14.