API Monitorong C

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

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

Генерирование событий выполнения

Приведенные ниже функции позволяют расширению отслеживать события при эмуляции выполнения кода 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_FireBranchEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset, PyObject *target_offset)

Вызовите событие BRANCH.

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.

Управление состоянием мониторинга

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