Поддержка Perf Maps¶Support for Perf Maps

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

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

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

int PyUnstable_PerfMapState_Init(void)¶

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

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

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

int PyUnstable_WritePerfMapEntry(const void *code_addr, size_t 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 map ещё не открыт. Возвращает 0 при успехе или те же коды ошибок, что и PyUnstable_PerfMapState_Init(), при неудаче.

void PyUnstable_PerfMapState_Fini(void)¶: Это нестабильное API. Оно может меняться без предупреждения в минорных версиях.

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

int PyUnstable_CopyPerfMapFile(const char *parent_filename)¶

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

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

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

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

int PyUnstable_PerfTrampoline_CompileCode(PyCodeObject *code)¶

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

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

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

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

Параметры:

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

Возвращает:

0 при успехе, -1 при ошибке.

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

int PyUnstable_PerfTrampoline_SetPersistAfterFork(int enable)¶

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

Устанавливает, должен ли perf trampoline сохраняться после форка.

Если enable истинно (не ноль): файл perf map остаётся открытым/действительным после форка. Дочерний процесс наследует все существующие записи perf map.
Если enable ложно (ноль): файл perf map закрывается после форка. Дочерний процесс получает пустую карту perf map.

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

Параметры:

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

Возвращает:

0 при успехе, -1 при ошибке.

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