`profiling.md`

141 строк · 17.7 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.14/c-api/profiling.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# Профилирование и трассировка89Интерпретатор Python предоставляет низкоуровневую поддержку для подключения средств профилирования и трассировки выполнения. Они используются в инструментах профилирования, отладки и анализа покрытия.1011Этот C-интерфейс позволяет коду профилирования или трассировки избежать накладных расходов на вызов через вызываемые объекты уровня Python, выполняя вместо этого прямой вызов C-функции. Основные характеристики механизма не изменились; интерфейс позволяет устанавливать функции трассировки для каждого потока, а базовые события, сообщаемые функции трассировки, такие же, как и в предыдущих версиях для функций трассировки уровня Python.1213#### `typedef int (*Py_tracefunc)(PyObject *obj, PyFrameObject *frame, int what, PyObject *arg)`1415Тип функции трассировки, регистрируемой с помощью [`PyEval_SetProfile()`](https://python-all.ru/3.14/c-api/profiling.html#c.PyEval_SetProfile) и [`PyEval_SetTrace()`](https://python-all.ru/3.14/c-api/profiling.html#c.PyEval_SetTrace). Первый параметр – это объект, переданный функции регистрации как *obj*, *frame* – это объект фрейма, к которому относится событие, *what* – одна из констант [`PyTrace_CALL`](https://python-all.ru/3.14/c-api/profiling.html#c.PyTrace_CALL), [`PyTrace_EXCEPTION`](https://python-all.ru/3.14/c-api/profiling.html#c.PyTrace_EXCEPTION), [`PyTrace_LINE`](https://python-all.ru/3.14/c-api/profiling.html#c.PyTrace_LINE), [`PyTrace_RETURN`](https://python-all.ru/3.14/c-api/profiling.html#c.PyTrace_RETURN), [`PyTrace_C_CALL`](https://python-all.ru/3.14/c-api/profiling.html#c.PyTrace_C_CALL), [`PyTrace_C_EXCEPTION`](https://python-all.ru/3.14/c-api/profiling.html#c.PyTrace_C_EXCEPTION), [`PyTrace_C_RETURN`](https://python-all.ru/3.14/c-api/profiling.html#c.PyTrace_C_RETURN) или [`PyTrace_OPCODE`](https://python-all.ru/3.14/c-api/profiling.html#c.PyTrace_OPCODE), а *arg* зависит от значения *what*:1617| Значение *what* | Смысл *arg* |18| --- | --- |19| [`PyTrace_CALL`](https://python-all.ru/3.14/c-api/profiling.html#c.PyTrace_CALL) | Всегда [`Py_None`](https://python-all.ru/3.14/c-api/none.html#c.Py_None). |20| [`PyTrace_EXCEPTION`](https://python-all.ru/3.14/c-api/profiling.html#c.PyTrace_EXCEPTION) | Информация об исключении, возвращаемая [`sys.exc_info()`](https://python-all.ru/3.14/library/sys.html#sys.exc_info). |21| [`PyTrace_LINE`](https://python-all.ru/3.14/c-api/profiling.html#c.PyTrace_LINE) | Всегда [`Py_None`](https://python-all.ru/3.14/c-api/none.html#c.Py_None). |22| [`PyTrace_RETURN`](https://python-all.ru/3.14/c-api/profiling.html#c.PyTrace_RETURN) | Значение, возвращаемое вызывающему коду, или `NULL`, если вызвано исключением. |23| [`PyTrace_C_CALL`](https://python-all.ru/3.14/c-api/profiling.html#c.PyTrace_C_CALL) | Вызываемый объект функции. |24| [`PyTrace_C_EXCEPTION`](https://python-all.ru/3.14/c-api/profiling.html#c.PyTrace_C_EXCEPTION) | Вызываемый объект функции. |25| [`PyTrace_C_RETURN`](https://python-all.ru/3.14/c-api/profiling.html#c.PyTrace_C_RETURN) | Вызываемый объект функции. |26| [`PyTrace_OPCODE`](https://python-all.ru/3.14/c-api/profiling.html#c.PyTrace_OPCODE) | Всегда [`Py_None`](https://python-all.ru/3.14/c-api/none.html#c.Py_None). |2728#### `int PyTrace_CALL`2930Значение параметра *what* для функции [`Py_tracefunc`](https://python-all.ru/3.14/c-api/profiling.html#c.Py_tracefunc), когда сообщается о новом вызове функции или метода, или о новом входе в генератор. Обратите внимание, что создание итератора для функции-генератора не сообщается, поскольку в соответствующем фрейме не происходит передачи управления байт-коду Python.3132#### `int PyTrace_EXCEPTION`3334Значение параметра *what* для функции [`Py_tracefunc`](https://python-all.ru/3.14/c-api/profiling.html#c.Py_tracefunc), когда возникло исключение. Функция обратного вызова вызывается с этим значением для *what* после обработки любого байт-кода, после которого исключение становится установленным в выполняемом фрейме. В результате, когда распространение исключения вызывает раскрутку стека Python, функция обратного вызова вызывается при возврате в каждый фрейм по мере распространения исключения. Только функции трассировки получают эти события; профилировщику они не нужны.3536#### `int PyTrace_LINE`3738Значение, передаваемое в качестве параметра *what* функции [`Py_tracefunc`](https://python-all.ru/3.14/c-api/profiling.html#c.Py_tracefunc) (но не функции профилирования), когда сообщается о событии номера строки. Его можно отключить для фрейма, установив [`f_trace_lines`](https://python-all.ru/3.14/reference/datamodel.html#frame.f_trace_lines) в *0* в этом фрейме.3940#### `int PyTrace_RETURN`4142Значение параметра *what* для функций [`Py_tracefunc`](https://python-all.ru/3.14/c-api/profiling.html#c.Py_tracefunc), когда вызов собирается вернуться.4344#### `int PyTrace_C_CALL`4546Значение параметра *what* для функций [`Py_tracefunc`](https://python-all.ru/3.14/c-api/profiling.html#c.Py_tracefunc), когда собирается быть вызвана C-функция.4748#### `int PyTrace_C_EXCEPTION`4950Значение параметра *what* для функций [`Py_tracefunc`](https://python-all.ru/3.14/c-api/profiling.html#c.Py_tracefunc), когда C-функция вызвала исключение.5152#### `int PyTrace_C_RETURN`5354Значение параметра *what* для функций [`Py_tracefunc`](https://python-all.ru/3.14/c-api/profiling.html#c.Py_tracefunc), когда C-функция вернулась.5556#### `int PyTrace_OPCODE`5758Значение параметра *what* для функций [`Py_tracefunc`](https://python-all.ru/3.14/c-api/profiling.html#c.Py_tracefunc) (но не функций профилирования), когда собирается быть выполнен новый опкод. Это событие не генерируется по умолчанию: его нужно явно запросить, установив [`f_trace_opcodes`](https://python-all.ru/3.14/reference/datamodel.html#frame.f_trace_opcodes) в *1* во фрейме.5960#### `void PyEval_SetProfile(Py_tracefunc func, PyObject *obj)`6162Устанавливает функцию профилирования в *func*. Параметр *obj* передаётся функции в качестве первого аргумента; это может быть любой объект Python или `NULL`. Если функции профилирования нужно поддерживать состояние, использование разных значений *obj* для каждого потока предоставляет удобное и потокобезопасное место для его хранения. Функция профилирования вызывается для всех отслеживаемых событий, кроме [`PyTrace_LINE`](https://python-all.ru/3.14/c-api/profiling.html#c.PyTrace_LINE), [`PyTrace_OPCODE`](https://python-all.ru/3.14/c-api/profiling.html#c.PyTrace_OPCODE) и [`PyTrace_EXCEPTION`](https://python-all.ru/3.14/c-api/profiling.html#c.PyTrace_EXCEPTION).6364См. также функцию [`sys.setprofile()`](https://python-all.ru/3.14/library/sys.html#sys.setprofile).6566Вызывающий должен иметь [прикреплённое состояние потока](https://python-all.ru/3.14/glossary.html#term-attached-thread-state).6768#### `void PyEval_SetProfileAllThreads(Py_tracefunc func, PyObject *obj)`6970Как [`PyEval_SetProfile()`](https://python-all.ru/3.14/c-api/profiling.html#c.PyEval_SetProfile), но устанавливает функцию профилирования во всех работающих потоках, принадлежащих текущему интерпретатору, а не только в текущем потоке.7172Вызывающий должен иметь [прикреплённое состояние потока](https://python-all.ru/3.14/glossary.html#term-attached-thread-state).7374Как и [`PyEval_SetProfile()`](https://python-all.ru/3.14/c-api/profiling.html#c.PyEval_SetProfile), эта функция игнорирует любые исключения, возникшие при установке функций профилирования во всех потоках.7576Добавлено в версии 3.12.7778#### `void PyEval_SetTrace(Py_tracefunc func, PyObject *obj)`7980Устанавливает функцию трассировки в *func*. Это похоже на [`PyEval_SetProfile()`](https://python-all.ru/3.14/c-api/profiling.html#c.PyEval_SetProfile), за исключением того, что функция трассировки получает события номеров строк и события на каждую операцию, но не получает событий, связанных с вызовом объектов функций C. Любая функция трассировки, зарегистрированная через [`PyEval_SetTrace()`](https://python-all.ru/3.14/c-api/profiling.html#c.PyEval_SetTrace), не будет получать [`PyTrace_C_CALL`](https://python-all.ru/3.14/c-api/profiling.html#c.PyTrace_C_CALL), [`PyTrace_C_EXCEPTION`](https://python-all.ru/3.14/c-api/profiling.html#c.PyTrace_C_EXCEPTION) или [`PyTrace_C_RETURN`](https://python-all.ru/3.14/c-api/profiling.html#c.PyTrace_C_RETURN) в качестве значения параметра *what*.8182См. также функцию [`sys.settrace()`](https://python-all.ru/3.14/library/sys.html#sys.settrace).8384Вызывающий должен иметь [прикреплённое состояние потока](https://python-all.ru/3.14/glossary.html#term-attached-thread-state).8586#### `void PyEval_SetTraceAllThreads(Py_tracefunc func, PyObject *obj)`8788Как [`PyEval_SetTrace()`](https://python-all.ru/3.14/c-api/profiling.html#c.PyEval_SetTrace), но устанавливает функцию трассировки во всех работающих потоках, принадлежащих текущему интерпретатору, а не только в текущем потоке.8990Вызывающий должен иметь [прикреплённое состояние потока](https://python-all.ru/3.14/glossary.html#term-attached-thread-state).9192Как и [`PyEval_SetTrace()`](https://python-all.ru/3.14/c-api/profiling.html#c.PyEval_SetTrace), эта функция игнорирует любые исключения, возникшие при установке функций трассировки во всех потоках.9394Добавлено в версии 3.12.9596# Трассировка ссылок9798Добавлено в версии 3.13.99100#### `typedef int (*PyRefTracer)(PyObject*, int event, void *data)`101102Тип функции трассировки, регистрируемой с помощью [`PyRefTracer_SetTracer()`](https://python-all.ru/3.14/c-api/profiling.html#c.PyRefTracer_SetTracer). Первый параметр – это объект Python, который только что был создан (когда **event** установлен в [`PyRefTracer_CREATE`](https://python-all.ru/3.14/c-api/profiling.html#c.PyRefTracer_CREATE)) или собирается быть уничтожен (когда **event** установлен в [`PyRefTracer_DESTROY`](https://python-all.ru/3.14/c-api/profiling.html#c.PyRefTracer_DESTROY)). Аргумент **data** – это непрозрачный указатель, который был предоставлен при вызове `PyRefTracer_SetTracer()`.103104Если регистрируется новая функция трассировки, заменяющая текущую, будет выполнен вызов функции трассировки с объектом, установленным в **NULL**, и **event**, установленным в [`PyRefTracer_TRACKER_REMOVED`](https://python-all.ru/3.14/c-api/profiling.html#c.PyRefTracer_TRACKER_REMOVED). Это произойдет непосредственно перед регистрацией новой функции.105106Добавлено в версии 3.13.107108#### `int PyRefTracer_CREATE`109110Значение параметра *event* для функций [`PyRefTracer`](https://python-all.ru/3.14/c-api/profiling.html#c.PyRefTracer), когда объект Python был создан.111112#### `int PyRefTracer_DESTROY`113114Значение параметра *event* для функций [`PyRefTracer`](https://python-all.ru/3.14/c-api/profiling.html#c.PyRefTracer), когда объект Python был уничтожен.115116#### `int PyRefTracer_TRACKER_REMOVED`117118Значение параметра *event* для функций [`PyRefTracer`](https://python-all.ru/3.14/c-api/profiling.html#c.PyRefTracer), когда текущий трассировщик собирается быть заменён новым.119120Добавлено в версии 3.14.121122#### `int PyRefTracer_SetTracer(PyRefTracer tracer, void *data)`123124Регистрирует функцию трассировки ссылок. Функция будет вызываться при создании нового объекта Python или при уничтожении объекта. Если указан **data**, это должен быть непрозрачный указатель, который будет предоставлен при вызове функции трассировки. Возвращает `0` в случае успеха. Устанавливает исключение и возвращает `-1` при ошибке.125126Обратите внимание, что функции трассировки **не должны** создавать объекты Python внутри, иначе вызов станет реентерабельным. Трассировщик также **не должен** очищать существующие исключения или устанавливать исключения. [Состояние потока](https://python-all.ru/3.14/glossary.html#term-thread-state) будет активно при каждом вызове функции трассировки.127128При вызове этой функции должно быть [присоединённое состояние потока](https://python-all.ru/3.14/glossary.html#term-attached-thread-state).129130Если другая функция трассировки уже была зарегистрирована, старая функция будет вызвана с **event**, установленным в [`PyRefTracer_TRACKER_REMOVED`](https://python-all.ru/3.14/c-api/profiling.html#c.PyRefTracer_TRACKER_REMOVED), непосредственно перед регистрацией новой функции.131132Добавлено в версии 3.13.133134#### `PyRefTracer PyRefTracer_GetTracer(void **data)`135136Возвращает зарегистрированную функцию трассировки ссылок и значение непрозрачного указателя данных, который был зарегистрирован при вызове [`PyRefTracer_SetTracer()`](https://python-all.ru/3.14/c-api/profiling.html#c.PyRefTracer_SetTracer). Если трассировщик не был зарегистрирован, эта функция вернёт NULL и установит указатель **data** в NULL.137138При вызове этой функции должно быть [присоединённое состояние потока](https://python-all.ru/3.14/glossary.html#term-attached-thread-state).139140Добавлено в версии 3.13.141