`monitoring.md`

143 строк · 13.0 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.15/c-api/monitoring.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# Мониторинг C API89Добавлено в версии 3.13.1011Расширению может потребоваться взаимодействие с системой мониторинга событий. Подписка на события и регистрация колбэков осуществляется через Python API, предоставленный в [`sys.monitoring`](https://python-all.ru/3.15/library/sys.monitoring.html#module-sys.monitoring).1213# Генерация событий выполнения1415Приведённые ниже функции позволяют расширению генерировать события мониторинга при эмуляции выполнения кода Python. Каждая из этих функций принимает структуру `PyMonitoringState`, содержащую краткую информацию о состоянии активации событий, а также аргументы события, которые включают `PyObject*`, представляющий объект кода, смещение инструкции и иногда дополнительные аргументы, специфичные для события (см. [`sys.monitoring`](https://python-all.ru/3.15/library/sys.monitoring.html#module-sys.monitoring) для подробностей о сигнатурах различных колбэков событий). Аргумент `codelike` должен быть экземпляром [`types.CodeType`](https://python-all.ru/3.15/library/types.html#types.CodeType) или типа, который его эмулирует.1617ВМ отключает трассировку при генерации события, поэтому пользовательскому коду делать это не нужно.1819Функции мониторинга не должны вызываться при установленном исключении, за исключением перечисленных ниже, которые работают с текущим исключением.2021#### `type PyMonitoringState`2223Представление состояния типа события. Выделяется пользователем, а его содержимое поддерживается функциями API мониторинга, описанными ниже.2425Все приведённые ниже функции возвращают 0 при успехе и -1 (с установленным исключением) при ошибке.2627Описания событий см. в [`sys.monitoring`](https://python-all.ru/3.15/library/sys.monitoring.html#module-sys.monitoring).2829#### `int PyMonitoring_FirePyStartEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset)`3031Генерирует событие `PY_START`.3233#### `int PyMonitoring_FirePyResumeEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset)`3435Генерирует событие `PY_RESUME`.3637#### `int PyMonitoring_FirePyReturnEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset, PyObject *retval)`3839Генерирует событие `PY_RETURN`.4041#### `int PyMonitoring_FirePyYieldEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset, PyObject *retval)`4243Генерирует событие `PY_YIELD`.4445#### `int PyMonitoring_FireCallEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset, PyObject *callable, PyObject *arg0)`4647Генерирует событие `CALL`.4849#### `int PyMonitoring_FireLineEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset, int lineno)`5051Генерирует событие `LINE`.5253#### `int PyMonitoring_FireJumpEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset, PyObject *target_offset)`5455Генерирует событие `JUMP`.5657#### `int PyMonitoring_FireBranchLeftEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset, PyObject *target_offset)`5859Генерирует событие `BRANCH_LEFT`.6061#### `int PyMonitoring_FireBranchRightEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset, PyObject *target_offset)`6263Генерирует событие `BRANCH_RIGHT`.6465#### `int PyMonitoring_FireCReturnEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset, PyObject *retval)`6667Генерирует событие `C_RETURN`.6869#### `int PyMonitoring_FirePyThrowEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset)`7071Генерирует событие `PY_THROW` с текущим исключением (как возвращено [`PyErr_GetRaisedException()`](https://python-all.ru/3.15/c-api/exceptions.html#c.PyErr_GetRaisedException)).7273#### `int PyMonitoring_FireRaiseEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset)`7475Генерирует событие `RAISE` с текущим исключением (как возвращено [`PyErr_GetRaisedException()`](https://python-all.ru/3.15/c-api/exceptions.html#c.PyErr_GetRaisedException)).7677#### `int PyMonitoring_FireCRaiseEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset)`7879Генерирует событие `C_RAISE` с текущим исключением (как возвращено [`PyErr_GetRaisedException()`](https://python-all.ru/3.15/c-api/exceptions.html#c.PyErr_GetRaisedException)).8081#### `int PyMonitoring_FireReraiseEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset)`8283Генерирует событие `RERAISE` с текущим исключением (как возвращено [`PyErr_GetRaisedException()`](https://python-all.ru/3.15/c-api/exceptions.html#c.PyErr_GetRaisedException)).8485#### `int PyMonitoring_FireExceptionHandledEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset)`8687Генерирует событие `EXCEPTION_HANDLED` с текущим исключением (как возвращено [`PyErr_GetRaisedException()`](https://python-all.ru/3.15/c-api/exceptions.html#c.PyErr_GetRaisedException)).8889#### `int PyMonitoring_FirePyUnwindEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset)`9091Генерирует событие `PY_UNWIND` с текущим исключением (как возвращено [`PyErr_GetRaisedException()`](https://python-all.ru/3.15/c-api/exceptions.html#c.PyErr_GetRaisedException)).9293#### `int PyMonitoring_FireStopIterationEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset, PyObject *value)`9495Генерирует событие `STOP_ITERATION`. Если `value` является экземпляром [`StopIteration`](https://python-all.ru/3.15/library/exceptions.html#StopIteration), он используется. В противном случае создаётся новый экземпляр `StopIteration` с `value` в качестве аргумента.9697## Управление состоянием мониторинга9899Состояниями мониторинга можно управлять с помощью областей мониторинга. Обычно область соответствует функции Python.100101#### `int PyMonitoring_EnterScope(PyMonitoringState *state_array, uint64_t *version, const uint8_t *event_types, Py_ssize_t length)`102103Входит в отслеживаемую область. `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`.104105Аргумент `version` – это указатель на значение, которое должно быть выделено пользователем вместе с `state_array` и инициализировано 0, а затем устанавливаться только самим `PyMonitoring_EnterScope()`. Это позволяет функции определять, изменились ли состояния событий с предыдущего вызова, и быстро возвращаться, если они не изменились.106107Области, упомянутые здесь, – это лексические области: функция, класс или метод. `PyMonitoring_EnterScope()` должен вызываться при каждом входе в лексическую область. Области можно повторно входить, используя те же *state\_array* и *version*, например, при эмуляции рекурсивной функции Python. Когда выполнение code-like приостанавливается, например, при эмуляции генератора, область нужно покинуть и войти снова.108109Макросы для *event\_types*:110111| Макрос | Событие |112| --- | --- |113| PY\_MONITORING\_EVENT\_BRANCH\_LEFT | [`BRANCH_LEFT`](https://python-all.ru/3.15/library/sys.monitoring.html#monitoring-event-BRANCH_LEFT) |114| PY\_MONITORING\_EVENT\_BRANCH\_RIGHT | [`BRANCH_RIGHT`](https://python-all.ru/3.15/library/sys.monitoring.html#monitoring-event-BRANCH_RIGHT) |115| PY\_MONITORING\_EVENT\_CALL | [`CALL`](https://python-all.ru/3.15/library/sys.monitoring.html#monitoring-event-CALL) |116| PY\_MONITORING\_EVENT\_C\_RAISE | [`C_RAISE`](https://python-all.ru/3.15/library/sys.monitoring.html#monitoring-event-C_RAISE) |117| PY\_MONITORING\_EVENT\_C\_RETURN | [`C_RETURN`](https://python-all.ru/3.15/library/sys.monitoring.html#monitoring-event-C_RETURN) |118| PY\_MONITORING\_EVENT\_EXCEPTION\_HANDLED | [`EXCEPTION_HANDLED`](https://python-all.ru/3.15/library/sys.monitoring.html#monitoring-event-EXCEPTION_HANDLED) |119| PY\_MONITORING\_EVENT\_INSTRUCTION | [`INSTRUCTION`](https://python-all.ru/3.15/library/sys.monitoring.html#monitoring-event-INSTRUCTION) |120| PY\_MONITORING\_EVENT\_JUMP | [`JUMP`](https://python-all.ru/3.15/library/sys.monitoring.html#monitoring-event-JUMP) |121| PY\_MONITORING\_EVENT\_LINE | [`LINE`](https://python-all.ru/3.15/library/sys.monitoring.html#monitoring-event-LINE) |122| PY\_MONITORING\_EVENT\_PY\_RESUME | [`PY_RESUME`](https://python-all.ru/3.15/library/sys.monitoring.html#monitoring-event-PY_RESUME) |123| PY\_MONITORING\_EVENT\_PY\_RETURN | [`PY_RETURN`](https://python-all.ru/3.15/library/sys.monitoring.html#monitoring-event-PY_RETURN) |124| PY\_MONITORING\_EVENT\_PY\_START | [`PY_START`](https://python-all.ru/3.15/library/sys.monitoring.html#monitoring-event-PY_START) |125| PY\_MONITORING\_EVENT\_PY\_THROW | [`PY_THROW`](https://python-all.ru/3.15/library/sys.monitoring.html#monitoring-event-PY_THROW) |126| PY\_MONITORING\_EVENT\_PY\_UNWIND | [`PY_UNWIND`](https://python-all.ru/3.15/library/sys.monitoring.html#monitoring-event-PY_UNWIND) |127| PY\_MONITORING\_EVENT\_PY\_YIELD | [`PY_YIELD`](https://python-all.ru/3.15/library/sys.monitoring.html#monitoring-event-PY_YIELD) |128| PY\_MONITORING\_EVENT\_RAISE | [`RAISE`](https://python-all.ru/3.15/library/sys.monitoring.html#monitoring-event-RAISE) |129| PY\_MONITORING\_EVENT\_RERAISE | [`RERAISE`](https://python-all.ru/3.15/library/sys.monitoring.html#monitoring-event-RERAISE) |130| PY\_MONITORING\_EVENT\_STOP\_ITERATION | [`STOP_ITERATION`](https://python-all.ru/3.15/library/sys.monitoring.html#monitoring-event-STOP_ITERATION) |131132#### `int PyMonitoring_ExitScope(void)`133134Завершает последнюю область видимости, открытую с помощью `PyMonitoring_EnterScope()`.135136#### `int PY_MONITORING_IS_INSTRUMENTED_EVENT(uint8_t ev)`137138Возвращает true, если событие, соответствующее идентификатору события *ev*, является [локальным событием](https://python-all.ru/3.15/library/sys.monitoring.html#monitoring-event-local).139140Добавлено в версии 3.13.141142[Soft deprecated](https://python-all.ru/3.15/glossary.html#term-soft-deprecated) since version 3.14.143