Поддержка карт Perf

На поддерживаемых платформах (на момент написания этой документации — только Linux) среда выполнения может использовать файлы карт perf, чтобы сделать функции Python видимыми для внешнего инструмента профилирования (например, perf). Работающий процесс может создать файл в каталоге /tmp, содержащий записи, которые сопоставляют участок исполняемого кода с именем. Этот интерфейс описан в документации инструмента Linux Perf.

В Python эти вспомогательные API могут использовать библиотеки и функции, которым требуется генерировать машинный код во время выполнения.

Обратите внимание, что для этих API не требуется удерживать присоединенное состояние потока.

int PyUnstable_PerfMapState_Init(void)

Это нестабильный API. Он может измениться без предупреждения в минорных выпусках.

Открывает файл /tmp/perf-$pid.map, если он ещё не открыт, и создает блокировку, обеспечивающую потокобезопасную запись в файл (при условии, что запись выполняется через PyUnstable_WritePerfMapEntry()). Обычно вызывать эту функцию явно не нужно: достаточно использовать PyUnstable_WritePerfMapEntry(), и при первом вызове она инициализирует состояние.

Возвращает 0 в случае успеха, -1, если не удалось создать или открыть файл карты perf, или -2, если не удалось создать блокировку. Проверьте errno, чтобы узнать причину сбоя.

int PyUnstable_WritePerfMapEntry(const void *code_addr, unsigned int code_size, const char *entry_name)

Это нестабильный API. Он может измениться без предупреждения в минорных выпусках.

Записывает одну запись в файл /tmp/perf-$pid.map. Эта функция потокобезопасна. Пример записи:

# address      size  name
7f3529fcf759 b     py::bar:/run/t.py

Перед записью записи вызовет PyUnstable_PerfMapState_Init(), если файл карты perf ещё не открыт. Возвращает 0 в случае успеха или те же коды ошибок, что и PyUnstable_PerfMapState_Init(), в случае сбоя.

void PyUnstable_PerfMapState_Fini(void)

Это нестабильный API. Он может измениться без предупреждения в минорных выпусках.

Закрывает файл карты perf, открытый функцией PyUnstable_PerfMapState_Init(). Среда выполнения вызывает эту функцию самостоятельно при завершении работы интерпретатора. Как правило, явно вызывать её не требуется, кроме особых случаев, например при создании ответвления процесса.

int PyUnstable_CopyPerfMapFile(const char *parent_filename)

Это нестабильный API. Он может измениться без предупреждения в минорных выпусках.

Открывает файл /tmp/perf-$pid.map и добавляет в него содержимое файла parent_filename.

Эта функция доступна на всех платформах, но создает вывод только на платформах с поддержкой карт perf (в настоящее время — только Linux). На остальных платформах она ничего не делает.

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

int PyUnstable_PerfTrampoline_CompileCode(PyCodeObject *code)

Это нестабильный API. Он может измениться без предупреждения в минорных выпусках.

Компилирует указанный объект кода с помощью текущего перф-трамплина.

«Текущий» трамплин — это трамплин, заданный средой выполнения или последним вызовом PyUnstable_PerfTrampoline_SetPersistAfterFork().

Если трамплин не задан, выполняется обычная компиляция (без записи в карту perf).

Параметры:

• code – Объект кода для компиляции.

Возвращает:

0 в случае успеха, -1 в случае сбоя.

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

int PyUnstable_PerfTrampoline_SetPersistAfterFork(int enable)

Это нестабильный API. Он может измениться без предупреждения в минорных выпусках.

Задает, должен ли перф-трамплин сохраняться после создания ответвления процесса.

• Если enable имеет значение true (не ноль), файл карты perf остается открытым и действительным после создания ответвления. Дочерний процесс наследует все существующие записи карты perf.
• Если enable имеет значение false (ноль), файл карты perf закрывается после создания ответвления. Дочерний процесс получает пустую карту perf.

По умолчанию: false (очищается при создании ответвления).

Параметры:

• enable – 1 для включения, 0 для отключения.

Возвращает:

0 в случае успеха, -1 в случае сбоя.

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