Инициализация, завершение и потоки

Перед инициализацией Python

В приложении, встраивающем Python, функция Py_Initialize() должна быть вызвана перед использованием любых других функций API Python/C; за исключением нескольких функций и глобальных переменных конфигурации.

Следующие функции можно безопасно вызывать до инициализации Python:

• Функции конфигурации:

  • PyImport_AppendInittab()
  • PyImport_ExtendInittab()
  • PyInitFrozenExtensions()
  • PyMem_SetAllocator()
  • PyMem_SetupDebugHooks()
  • PyObject_SetArenaAllocator()
  • Py_SetPath()
  • Py_SetProgramName()
  • Py_SetPythonHome()
  • Py_SetStandardStreamEncoding()
  • PySys_AddWarnOption()
  • PySys_AddXOption()
  • PySys_ResetWarnOptions()

• Информационные функции:

  • Py_IsInitialized()
  • PyMem_GetAllocator()
  • PyObject_GetArenaAllocator()
  • Py_GetBuildInfo()
  • Py_GetCompiler()
  • Py_GetCopyright()
  • Py_GetPlatform()
  • Py_GetVersion()

• Утилиты:

  • Py_DecodeLocale()

• Аллокаторы памяти:

  • PyMem_RawMalloc()
  • PyMem_RawRealloc()
  • PyMem_RawCalloc()
  • PyMem_RawFree()

Глобальные переменные конфигурации

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

Когда флаг устанавливается опцией, значение флага равно количеству раз, когда эта опция была установлена. Например, -b устанавливает Py_BytesWarningFlag в 1, а -bb устанавливает Py_BytesWarningFlag в 2.

int Py_BytesWarningFlag

Выдает предупреждение при сравнении bytes или bytearray с str, или bytes с int. Выдает ошибку, если значение больше или равно 2.

Устанавливается опцией -b.

int Py_DebugFlag

Включает вывод отладки синтаксического анализа (только для опытных пользователей, зависит от опций компиляции).

Устанавливается опцией -d и переменной окружения PYTHONDEBUG.

int Py_DontWriteBytecodeFlag

Если установлено в ненулевое значение, Python не будет пытаться записать файлы .pyc при импорте исходных модулей.

Устанавливается опцией -B и переменной окружения PYTHONDONTWRITEBYTECODE.

int Py_FrozenFlag

Подавляет сообщения об ошибках при вычислении пути поиска модулей в Py_GetPath().

Внутренний флаг, используемый программами _freeze_importlib и frozenmain.

int Py_HashRandomizationFlag

Устанавливается в 1 если переменная окружения PYTHONHASHSEED имеет ненулевое значение.

Если флаг ненулевой, считывает переменную окружения PYTHONHASHSEED для инициализации секредного семени хэширования.

int Py_IgnoreEnvironmentFlag

Игнорирует все переменные окружения PYTHON*, например, PYTHONPATH и PYTHONHOME, которые могут быть установлены.

Устанавливается опциями -E и -I.

int Py_InspectFlag

Когда скрипт передается в качестве первого аргумента или используется опция -c, переходит в интерактивный режим после выполнения скрипта или команды, даже если sys.stdin не кажется терминалом.

Устанавливается опцией -i и переменной окружения PYTHONINSPECT.

int Py_InteractiveFlag

Устанавливается опцией -i.

int Py_IsolatedFlag

Запускает Python в изолированном режиме. В изолированном режиме sys.path не содержит ни директорию скрипта, ни директорию site-packages пользователя.

Устанавливается опцией -I.

Введено в версии 3.4.

int Py_LegacyWindowsFSEncodingFlag

Если флаг ненулевой, использует кодировку mbcs вместо UTF-8 для кодировки файловой системы.

Устанавливается в 1 если переменная окружения PYTHONLEGACYWINDOWSFSENCODING имеет ненулевое значение.

См. PEP 529 для получения дополнительных сведений.

Доступность: Windows.

int Py_LegacyWindowsStdioFlag

Если флаг ненулевой, использует io.FileIO вместо WindowsConsoleIO для стандартных потоков sys.

Устанавливается в 1 если переменная окружения PYTHONLEGACYWINDOWSSTDIO имеет ненулевое значение.

См. PEP 528 для получения дополнительных сведений.

Доступность: Windows.

int Py_NoSiteFlag

Отключает импорт модуля site и зависящие от сайта манипуляции с sys.path. Также отключает эти манипуляции, если site явным образом импортируется позже (вызовите site.main(), если хотите, чтобы они были вызваны).

Устанавливается опцией -S.

int Py_NoUserSiteDirectory

Не добавляет user site-packages directory в sys.path.

Устанавливается опциями -s и -I, и переменной окружения PYTHONNOUSERSITE.

int Py_OptimizeFlag

Устанавливается опцией -O и переменной окружения PYTHONOPTIMIZE.

int Py_QuietFlag

Не отображать сообщения об авторских правах и версии, даже в интерактивном режиме.

Устанавливается опцией -q.

Введено в версии 3.2.

int Py_UnbufferedStdioFlag

Принудительно устанавливает небуферизованные стандартные потоки stdout и stderr.

Устанавливается опцией -u и переменной окружения PYTHONUNBUFFERED.

int Py_VerboseFlag

Выводить сообщение каждый раз, когда инициализируется модуль, показывая место (имя файла или встроенный модуль), откуда он загружается. Если значение больше или равно 2, выводить сообщение для каждого файла, проверяемого при поиске модуля. Также предоставляет информацию о очистке модулей при выходе.

Устанавливается опцией -v и переменной окружения PYTHONVERBOSE.

Инициализация и завершение работы интерпретатора

void Py_Initialize()

Инициализирует интерпретатор Python. В приложении, которое включает Python, это должно вызываться перед использованием любых других функций Python/C API; см. Перед инициализацией Python для нескольких исключений.

Это инициализирует таблицу загруженных модулей (sys.modules), и создаёт базовые модули builtins, __main__ и sys. Также инициализируется путь поиска модулей (sys.path). Оно не устанавливает sys.argv; используйте PySys_SetArgvEx() для этого. Это пустая операция при повторном вызове (без вызова Py_FinalizeEx() прежде). Отсутствие возвращаемого значения; ошибка, если инициализация завершится неудачно.

Примечание

В Windows, изменяет режим консоли с O_TEXT на O_BINARY, что также повлияет на использование консоли не связанными с Python программами, использующими C Runtime.

void Py_InitializeEx(int initsigs)

Эта функция работает так же, как Py_Initialize(), если initsigs равно 1. Если initsigs равно 0, она пропускает регистрацию обработки сигналов, что может быть полезно при внедрении Python.

int Py_IsInitialized()

Возвращает true (ненулевое значение), если интерпретатор Python был инициализирован, false (нулевое значение), если нет. После вызова Py_FinalizeEx(), это возвращает false до тех пор, пока Py_Initialize() не будет вызван снова.

int Py_FinalizeEx()

Отменяет все инициализации, сделанные Py_Initialize() и последующими вызовами функций Python/C API, и уничтожает все дочерние интерпретаторы (см. Py_NewInterpreter() ниже), которые были созданы и еще не уничтожены с момента последнего вызова Py_Initialize(). В идеале, это освобождает всю память, выделенную интерпретатором Python. Это пустая операция при повторном вызове (без повторного вызова Py_Initialize()). Обычно возвращается 0. Если при завершении были ошибки (очистка буферизованных данных), возвращается -1.

Эта функция предоставляется по нескольким причинам. Приложение, которое включает интерпретатор Python, может захотеть перезапустить Python, не перезапуская само приложение. Приложение, которое загрузило интерпретатор Python из динамически загружаемой библиотеки (или DLL), может захотеть освободить всю память, выделенную Python, перед разгрузкой DLL. При поиске утечек памяти в приложении разработчик может захотеть освободить всю память, выделенную Python, перед выходом из приложения.

Ошибки и замечания: Уничтожение модулей и объектов в модулях происходит в случайном порядке; это может привести к ошибке деструкторов (__del__() методы), если они зависят от других объектов (даже функций) или модулей. Динамически загруженные расширенные модули, загруженные Python, не разгружаются. Небольшое количество памяти, выделенной интерпретатором Python, может не быть освобождено (если вы обнаружили утечку, сообщите об этом). Память, занятая циклическими ссылками между объектами, не освобождается. Некоторая память, выделенная расширенными модулями, может не быть освобождена. Некоторые расширения могут работать неправильно, если их функция инициализации вызывается более одного раза; это может произойти, если приложение вызовет Py_Initialize() и Py_FinalizeEx() более одного раза.

Вызывает событие аудита cpython._PySys_ClearAuditHooks без аргументов.

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

void Py_Finalize()

Это обратная совместимая версия Py_FinalizeEx(), которая игнорирует возвращаемое значение.

Параметры, общие для всего процесса

int Py_SetStandardStreamEncoding(const char *encoding, const char *errors)

Эту функцию следует вызвать до Py_Initialize(), если она вообще вызывается. Она определяет кодировку и обработку ошибок для стандартного ввода/вывода, значения которых совпадают со значениями в str.encode().

Она переопределяет значения PYTHONIOENCODING и позволяет коду вставки управлять кодировкой ввода/вывода, когда переменная среды не работает.

encoding и/или errors могут быть NULL для использования PYTHONIOENCODING и/или значения по умолчанию (в зависимости от других настроек).

Обратите внимание, что sys.stderr всегда использует обработчик ошибок “backslashreplace”, независимо от этого (или любого другого) параметра.

Если вызывается Py_FinalizeEx(), эту функцию нужно вызвать снова, чтобы она повлияла на последующие вызовы Py_Initialize().

Возвращает 0 при успешном выполнении, ненулевое значение при ошибке (например, при вызове после того, как интерпретатор уже был инициализирован).

Введено в версии 3.4.

void Py_SetProgramName(const wchar_t *name)

Эту функцию следует вызвать перед первым вызовом Py_Initialize(), если она вообще вызывается. Она сообщает интерпретатору значение аргумента argv[0] для функции main() программы (преобразованного в символы широкого диапазона). Это используется функциями Py_GetPath() и некоторыми другими функциями ниже для поиска библиотек Python Runtime относительно исполняемого файла интерпретатора. Значение по умолчанию — 'python'. Аргумент должен указывать на строку с нулевым завершением символов широкого диапазона в статическом хранилище, содержимое которой не будет изменено в течение выполнения программы. Никакой код в интерпретаторе Python не изменит содержимое этого хранилища.

Используйте Py_DecodeLocale() для декодирования строки байтов, чтобы получить строку wchar_*.

wchar* Py_GetProgramName()

Возвращает имя программы, заданное с помощью Py_SetProgramName(), или значение по умолчанию. Возвращаемая строка указывает на статическое хранилище; вызывающий код не должен изменять его значение.

wchar_t* Py_GetPrefix()

Возвращает префикс для установленных платформенно-независимых файлов. Он выводится по ряду сложных правил из имени программы, заданного с помощью Py_SetProgramName(), и некоторых переменных среды; например, если имя программы '/usr/local/bin/python', то префикс равен '/usr/local'. Возвращаемая строка указывает на статическое хранилище; вызывающий код не должен изменять ее значение. Это соответствует переменной prefix в главном Makefile и аргументу --prefix скрипта configure во время сборки. Значение доступно коду Python как sys.prefix. Полезно только в Unix. См. также следующую функцию.

wchar_t* Py_GetExecPrefix()

Возвращает exec-префикс для установленных файлов, зависящих от платформы. Он выводится по ряду сложных правил из имени программы, заданного с помощью Py_SetProgramName(), и некоторых переменных среды; например, если имя программы '/usr/local/bin/python', то exec-префикс равен '/usr/local'. Возвращаемая строка указывает на статическое хранилище; вызывающий код не должен изменять ее значение. Это соответствует переменной exec_prefix в главном Makefile и аргументу --exec-prefix скрипта configure во время сборки. Значение доступно коду Python как sys.exec_prefix. Полезно только в Unix.

Предыстория: exec-префикс отличается от префикса, когда файлы, зависящие от платформы (например, исполняемые файлы и динамические библиотеки), устанавливаются в разные каталоги. В типичной установке платформозависимые файлы могут устанавливаться в подкаталоге /usr/local/plat, а платформенно-независимые — в /usr/local.

В общем случае платформа — это сочетание аппаратных и программных семейств. Например, Sparc-машины под управлением операционной системы Solaris 2.x считаются одной платформой, но Intel-машины под управлением Solaris 2.x — другой, а Intel-машины под управлением Linux — еще одной платформой. Разные основные версии одной и той же операционной системы, как правило, также образуют разные платформы. В случае операционных систем, отличных от Unix, ситуация иная; стратегии установки в этих системах настолько различаются, что префикс и exec-префикс бессмысленны и устанавливаются в пустую строку. Обратите внимание, что скомпилированные файлы байткода Python являются платформенно-независимыми (но не независимыми от версии Python, с помощью которой они были скомпилированы!).

Администраторы систем знают, как настроить программы mount или automount, чтобы разделить /usr/local между платформами, при этом /usr/local/plat будет другим файловым каталогом для каждой платформы.

wchar_t* Py_GetProgramFullPath()

Возвращает полное имя программы интерпретатора Python; оно вычисляется как побочный эффект получения пути поиска модулей по умолчанию из имени программы (заданного Py_SetProgramName() выше). Возвращаемая строка указывает на статическое хранилище; вызывающий код не должен изменять ее значение. Значение доступно коду Python как sys.executable.

wchar_t* Py_GetPath()

Возвращает путь поиска модулей по умолчанию; он вычисляется из имени программы (заданного Py_SetProgramName() выше) и некоторых переменных среды. Возвращаемая строка состоит из последовательности имён каталогов, разделенных платформенно-зависимым разделителем. Разделитель — ':' в Unix и macOS, ';' в Windows. Возвращаемая строка указывает на статическое хранилище; вызывающий код не должен изменять ее значение. Список sys.path инициализируется этим значением при запуске интерпретатора; он может быть (и обычно является) изменён позднее для изменения пути поиска при загрузке модулей.

void Py_SetPath(const wchar_t *)

Устанавливает путь поиска модулей по умолчанию. Если эта функция вызывается до Py_Initialize(), то Py_GetPath() не будет пытаться вычислить путь поиска по умолчанию, а вместо этого использует предоставленный. Это полезно, если Python встроен приложением, которое полностью знает местоположение всех модулей. Компоненты пути должны быть разделены платформенно-зависимым разделителем, который равен ':' в Unix и macOS, ';' в Windows.

Это также приводит к тому, что sys.executable устанавливается в полный путь программы (см. Py_GetProgramFullPath()) и sys.prefix и sys.exec_prefix становятся пустыми. Вызывающий код должен сам изменить эти значения, если это необходимо, после вызова Py_Initialize().

Используйте Py_DecodeLocale() для декодирования строки байтов, чтобы получить строку wchar_*.

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

Изменено в версии 3.8: Теперь для sys.executable используется полный путь к программе, а не имя программы.

const char* Py_GetVersion()

Возвращает версию этой интерпретатора Python. Это строка, которая выглядит примерно так

"3.0a5+ (py3k:63103M, May 12 2008, 00:53:55) \n[GCC 4.2.3]"

Первое слово (до первого пробела) — текущая версия Python; первые символы — главная и второстепенная версия, разделённые точкой. Возвращаемая строка указывает на статическое хранилище; вызывающий код не должен изменять ее значение. Значение доступно коду Python как sys.version.

const char* Py_GetPlatform()

Возвращает идентификатор платформы для текущей платформы. В Unix он формируется из «официального» названия операционной системы, преобразованного в нижний регистр, за которым следует номер основной версии; например, для Solaris 2.x, который также известен как SunOS 5.x, значение равно 'sunos5'. В macOS — 'darwin'. В Windows — 'win'. Возвращаемая строка указывает на статическое хранилище; вызывающий код не должен изменять ее значение. Значение доступно коду Python как sys.platform.

const char* Py_GetCopyright()

Возвращает строку официального авторского права для текущей версии Python, например

'Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam'

Возвращаемая строка указывает на статическую память; вызывающая сторона не должна изменять её значение. Значение доступно коду Python как sys.copyright.

const char* Py_GetCompiler()

Возвращает указание на компилятор, использованный для построения текущей версии Python, в квадратных скобках, например:

"[GCC 2.7.2.2]"

Возвращаемая строка указывает на статическую память; вызывающая сторона не должна изменять её значение. Значение доступно коду Python в переменной sys.version.

const char* Py_GetBuildInfo()

Возвращает информацию о номере версии и дате и времени сборки текущего интерпретатора Python, например

"#67, Aug  1 1997, 22:34:28"

Возвращаемая строка указывает на статическую память; вызывающая сторона не должна изменять её значение. Значение доступно коду Python в переменной sys.version.

void PySys_SetArgvEx(int argc, wchar_t **argv, int updatepath)

Устанавливает sys.argv на основе argc и argv. Эти параметры похожи на те, что передаются в функцию main() программы, с той разницей, что первый элемент должен ссылаться на имя файла сценария для выполнения, а не на исполняемый файл, содержащий интерпретатор Python. Если нет сценария, который будет запущен, первый элемент в argv может быть пустой строкой. Если эта функция не удаётся инициализировать sys.argv, сигнализируется фатальная ошибка с использованием Py_FatalError().

Если updatepath равно нулю, это всё, что делает функция. Если updatepath не равно нулю, функция также изменяет sys.path в соответствии со следующим алгоритмом:

• Если имя существующего сценария передано в argv[0], абсолютный путь к каталогу, где находится сценарий, добавляется в начало sys.path.
• В противном случае (то есть, если argc равно 0 или argv[0] не указывает на существующее имя файла), пустая строка добавляется в начало sys.path, что эквивалентно добавлению текущей рабочей директории (".").

Используйте Py_DecodeLocale() для декодирования строки байтов, чтобы получить wchar_* строку.

Примечание

Рекомендуется, чтобы приложения, встраивающие интерпретатор Python с целью выполнения не только одного сценария, передавали 0 в качестве updatepath и обновляли sys.path самостоятельно, если это необходимо. См. CVE-2008-5983.

В версиях до 3.1.3 можно добиться того же эффекта, вручную удалив первый элемент sys.path после вызова PySys_SetArgv(), например, используя:

PyRun_SimpleString("import sys; sys.path.pop(0)\n");

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

void PySys_SetArgv(int argc, wchar_t **argv)

Эта функция работает как PySys_SetArgvEx() со значением updatepath, установленным в 1, если интерпретатор python не был запущен с -I.

Используйте Py_DecodeLocale() для декодирования строки байтов, чтобы получить wchar_* строку.

Изменено в версии 3.4: Значение updatepath зависит от -I.

void Py_SetPythonHome(const wchar_t *home)

Устанавливает стандартную домашнюю директорию, то есть расположение стандартных библиотек Python. См. PYTHONHOME для объяснения аргумента строки.

Аргумент должен указывать на строку с нулевым завершением в статической памяти, содержимое которой не изменится в течение выполнения программы. Ни один код в интерпретаторе Python не изменит содержимое этой памяти.

Используйте Py_DecodeLocale() для декодирования строки байтов, чтобы получить wchar_* строку.

w_char* Py_GetPythonHome()

Возвращает стандартную домашнюю директорию, то есть значение, установленное предыдущим вызовом Py_SetPythonHome(), или значение переменной окружения PYTHONHOME, если она установлена.

Состояние потоков и глобальная блокировка интерпретатора

Интерпретатор Python не является полностью многопоточным. Для поддержки многопоточных программ Python существует глобальная блокировка, называемая глобальной блокировкой интерпретатора или GIL, которую должен удерживать текущий поток перед безопасным доступом к объектам Python. Без блокировки даже самые простые операции могут привести к проблемам в многопоточной программе: например, когда два потока одновременно увеличивают счетчик ссылок одного и того же объекта, счетчик ссылок может быть увеличен только один раз вместо двух.

Поэтому существует правило, что только поток, получивший GIL, может выполнять операции с объектами Python или вызывать функции Python/C API. Для эмуляции одновременного выполнения интерпретатор регулярно пытается переключать потоки (см. sys.setswitchinterval()). Блокировка также снимается при потенциально блокирующих операциях ввода-вывода, таких как чтение или запись файла, чтобы другие потоки Python могли работать тем временем.

Интерпретатор Python сохраняет некоторые данные, специфичные для потока, в структуре данных, называемой PyThreadState. Также существует одна глобальная переменная, указывающая на текущее состояние PyThreadState: ее можно получить, используя PyThreadState_Get().

Save the thread state in a local variable.
Release the global interpreter lock.
... Do some blocking I/O operation ...
Reacquire the global interpreter lock.
Restore the thread state from the local variable.

Py_BEGIN_ALLOW_THREADS
... Do some blocking I/O operation ...
Py_END_ALLOW_THREADS

PyThreadState *_save;

_save = PyEval_SaveThread();
... Do some blocking I/O operation ...
PyEval_RestoreThread(_save);

PyGILState_STATE gstate;
gstate = PyGILState_Ensure();

/* Perform Python actions here. */
result = CallSomeFunction();
/* evaluate result or handle exception */

/* Release the thread. No Python API allowed beyond this point. */
PyGILState_Release(gstate);

Поддержка под-интерпретаторов

Хотя в большинстве случаев вы будете использовать только один интерпретатор Python, есть случаи, когда вам нужно создать несколько независимых интерпретаторов в одном процессе и, возможно, даже в одном потоке. Под-интерпретаторы позволяют вам это сделать.

«Главный» интерпретатор — это первый созданный при инициализации среды выполнения. Обычно это единственный интерпретатор Python в процессе. В отличие от под-интерпретаторов, главный интерпретатор имеет уникальные обязанности, относящиеся ко всему процессу, такие как обработка сигналов. Он также отвечает за выполнение во время инициализации среды выполнения и обычно является активным интерпретатором во время завершения среды выполнения. Функция PyInterpreterState_Main() возвращает указатель на его состояние.

Вы можете переключаться между под-интерпретаторами с помощью функции PyThreadState_Swap(). Вы можете создавать и удалять их с помощью следующих функций:

PyThreadState* Py_NewInterpreter()

Создать новый под-интерпретатор. Это (почти) полностью отдельная среда для выполнения кода Python. В частности, новый интерпретатор имеет отдельные, независимые версии всех импортированных модулей, включая базовые модули builtins, __main__ и sys. Таблица загруженных модулей (sys.modules) и путь поиска модулей (sys.path) также отдельные. Новая среда не имеет переменной sys.argv. Она имеет новые стандартные потоковые объекты файла sys.stdin, sys.stdout и sys.stderr (однако они ссылаются на те же самые основанные файлы).

Значение возврата указывает на первое состояние потока, созданное в новом под-интерпретаторе. Это состояние потока создается в текущем состоянии потока. Обратите внимание, что фактически не создается ни одного потока; см. обсуждение состояний потоков ниже. Если создание нового интерпретатора не удалось, возвращается NULL; исключение не устанавливается, поскольку состояние исключения хранится в текущем состоянии потока, и текущего состояния потока может и не быть. (Как и все другие функции API Python/C, блокировка глобального интерпретатора должна быть захвачена перед вызовом этой функции и все еще удерживается при ее возврате; однако, в отличие от большинства других функций API Python/C, текущее состояние потока при входе может отсутствовать).

Модули расширения разделяются между (под-)интерпретаторами следующим образом:

• Для модулей, использующих многофазную инициализацию, например, PyModule_FromDefAndSpec(), для каждого интерпретатора создается и инициализируется отдельный объект модуля. Только переменные статические и глобальные на уровне C разделяются между этими объектами модулей.

• Для модулей, использующих однофазную инициализацию, например, PyModule_Create(), в первый раз, когда конкретный модуль расширения импортируется, он инициализируется в обычном режиме, и копия словаря модуля (поверхностная) сохраняется. Когда тот же модуль расширения импортируется другим (под-)интерпретатором, инициализируется новый модуль и заполняется содержимым этой копии; функция init модуля не вызывается. Таким образом, объекты в словаре модуля разделяются между (под-)интерпретаторами, что может вызвать нежелательное поведение (см. Ошибки и замечания ниже).

  Обратите внимание, что это отличается от того, что происходит, когда модуль расширения импортируется после того, как интерпретатор был полностью перезапущен путем вызова Py_FinalizeEx() и Py_Initialize(); в этом случае функция initmodule модуля вызывается снова. Как и при многофазной инициализации, это означает, что только статические и глобальные переменные на уровне C разделяются между этими модулями.

void Py_EndInterpreter(PyThreadState *tstate)

Удалить (под-)интерпретатор, представленный данным состоянием потока. Данное состояние потока должно быть текущим состоянием потока. См. обсуждение состояний потоков ниже. Когда вызов возвращается, текущее состояние потока — NULL. Все состояния потоков, связанные с этим интерпретатором, уничтожаются. (Блокировка глобального интерпретатора должна быть захвачена перед вызовом этой функции и все еще удерживается при ее возврате.) Py_FinalizeEx() уничтожит все под-интерпретаторы, которые не были явно уничтожены на этом этапе.

Асинхронные уведомления

Предоставлен механизм для асинхронных уведомлений основной интерпретирующей нити. Эти уведомления представляют собой указатель на функцию и аргумент типа указатель на void.

int Py_AddPendingCall(int (*func)(void *), void *arg)

Планирует вызов функции из основной интерпретирующей нити. При успехе возвращается 0 и func помещается в очередь для вызова в основной нити. При ошибке возвращается -1 без установки исключения.

После успешного помещения в очередь, func будет в конечном итоге вызвана из основной интерпретирующей нити с аргументом arg. Она будет вызвана асинхронно относительно обычно выполняемого Python-кода, но при соблюдении этих условий:

• на границе байт-кода;
• с удержанием основной нитью глобальной блокировки интерпретатора (func может поэтому использовать весь C API).

func должна возвращать 0 при успехе или -1 при ошибке с установленным исключением. func не будет прервана для выполнения другого асинхронного уведомления рекурсивно, но она все же может быть прервана для переключения нитей, если глобальная блокировка интерпретатора освобождена.

Эта функция не нуждается в текущем состоянии нити для выполнения и не требует глобальной блокировки интерпретатора.

Для вызова этой функции в подинтерпретаторе вызывающий должен удерживать GIL. В противном случае функция func может быть запланирована на вызов из неправильного интерпретатора.

Предупреждение

Это функция низкого уровня, полезная только в очень особых случаях. Нет гарантии, что func будет вызвана как можно быстрее. Если основная нить занята выполнением системного вызова, func не будет вызвана до возврата из системного вызова. Эта функция, как правило, не подходит для вызова Python-кода из произвольных C-нитей. Используйте вместо этого API PyGILState.

Изменено в версии 3.9: Если эта функция вызывается в подинтерпретаторе, функция func теперь планируется для вызова из подинтерпретатора, а не из основного интерпретатора. Каждый подинтерпретатор теперь имеет свой собственный список запланированных вызовов.

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

Профилирование и отслеживание

Интерпретатор Python предоставляет некоторую поддержку низкого уровня для подключения средств профилирования и отслеживания выполнения. Они используются для профилирования, отладки и анализа покрытия.

Этот C интерфейс позволяет коду профилирования или отслеживания избежать накладных расходов на вызов через вызываемые объекты на уровне Python, вместо этого выполняя прямой C-вызов. Существенные атрибуты средства не изменились; интерфейс позволяет устанавливать функции отслеживания по каждой нити, и базовые события, сообщаемые функции отслеживания, такие же, как сообщались функциям отслеживания на уровне Python в предыдущих версиях.

int (*Py_tracefunc)(PyObject *obj, PyFrameObject *frame, int what, PyObject *arg)

Тип функции отслеживания, зарегистрированной с помощью PyEval_SetProfile() и PyEval_SetTrace(). Первый параметр — объект, переданный функции регистрации как obj, frame — объект фрейма, к которому относится событие, what — одна из констант PyTrace_CALL, PyTrace_EXCEPTION, PyTrace_LINE, PyTrace_RETURN, PyTrace_C_CALL, PyTrace_C_EXCEPTION, PyTrace_C_RETURN, или PyTrace_OPCODE, а arg зависит от значения what:

Значение what	Значение arg
PyTrace_CALL	Всегда Py_None.
PyTrace_EXCEPTION	Информация об исключении, возвращаемая sys.exc_info().
PyTrace_LINE	Всегда Py_None.
PyTrace_RETURN	Возвращаемое значение вызывающей стороне, или NULL если вызвано исключением.
PyTrace_C_CALL	Объект функции, который вызывается.
PyTrace_C_EXCEPTION	Объект функции, который вызывается.
PyTrace_C_RETURN	Объект функции, который вызывается.
PyTrace_OPCODE	Всегда Py_None.

int PyTrace_CALL

Значение параметра what для функции Py_tracefunc при сообщении о новом вызове функции или метода или новом входе в генератор. Обратите внимание, что создание итератора для генераторной функции не сообщается, так как нет передачи управления байт-коду в соответствующем фрейме.

int PyTrace_EXCEPTION

Значение параметра what для функции Py_tracefunc при возникновении исключения. Функция обратного вызова вызывается с этим значением для what после обработки любого байт-кода, после чего исключение устанавливается в выполняемом фрейме. В результате, при распространении исключения, вызывая разворачивание Python стека, обратный вызов вызывается при возврате в каждый фрейм, поскольку исключение распространяется. Только функции отслеживания получают эти события; они не нужны профилировщику.

int PyTrace_LINE

Значение, передаваемое в качестве параметра what для функции Py_tracefunc (но не функции профилирования) при сообщении об событии номера строки. Он может быть отключён для фрейма, установив f_trace_lines на 0 в этом фрейме.

int PyTrace_RETURN

Значение для параметра what для функций Py_tracefunc при приближающемся возвращении вызова.

int PyTrace_C_CALL

Значение для параметра what функций Py_tracefunc при вызове C-функции.

int PyTrace_C_EXCEPTION

Значение для параметра what функций Py_tracefunc при возникновении исключения в C-функции.

int PyTrace_C_RETURN

Значение для параметра what функций Py_tracefunc при возвращении C-функции.

int PyTrace_OPCODE

Значение параметра what функций Py_tracefunc (но не функций профилирования) при вызове нового оператора. Это событие не генерируется по умолчанию: оно должно быть явно запрошено, установив f_trace_opcodes в 1 в фрейме.

void PyEval_SetProfile(Py_tracefunc func, PyObject *obj)

Устанавливает функцию профилирования на func. Параметр obj передается функции в качестве её первого параметра и может быть любым Python объектом или NULL. Если функции профилирования требуется сохранять состояние, использование разных значений obj для каждой нити предоставляет удобное и безопасное место для его хранения. Функция профилирования вызывается для всех отслеживаемых событий, за исключением PyTrace_LINE PyTrace_OPCODE и PyTrace_EXCEPTION.

Вызывающий должен удерживать GIL.

void PyEval_SetTrace(Py_tracefunc func, PyObject *obj)

Устанавливает функцию отслеживания на func. Это аналогично PyEval_SetProfile(), за исключением того, что функция отслеживания получает события номера строки и события по каждому оператору, но не получает события, связанные с вызовами C-функций. Любая функция отслеживания, зарегистрированная с помощью PyEval_SetTrace(), не получит PyTrace_C_CALL, PyTrace_C_EXCEPTION или PyTrace_C_RETURN в качестве значения параметра what.

Вызывающий должен удерживать GIL.

Расширенная поддержка отладчика

Эти функции предназначены только для использования расширенными инструментами отладки.

PyInterpreterState* PyInterpreterState_Head()

Возвращает объект состояния интерпретатора, находящийся в начале списка всех таких объектов.

PyInterpreterState* PyInterpreterState_Main()

Возвращает основной объект состояния интерпретатора.

PyInterpreterState* PyInterpreterState_Next(PyInterpreterState *interp)

Возвращает следующий объект состояния интерпретатора после interp в списке всех таких объектов.

PyThreadState * PyInterpreterState_ThreadHead(PyInterpreterState *interp)

Возвращает указатель на первый объект PyThreadState в списке потоков, связанных с интерпретатором interp.

PyThreadState* PyThreadState_Next(PyThreadState *tstate)

Возвращает следующий объект состояния потока после tstate в списке всех таких объектов, принадлежащих тому же объекту PyInterpreterState.

Поддержка локального хранения данных в потоке

Интерпретатор Python предоставляет поддержку низкого уровня для локального хранения данных в потоке (TLS), которая оборачивает базовую реализацию TLS для поддержки API локального хранения данных на уровне Python (threading.local). API CPython на C-уровне аналогичен API pthreads и Windows: используется ключ потока и функции для ассоциации значения void* с каждым потоком.

Флажок глобальной блокировки (GIL) не требуется при вызове этих функций; они обеспечивают свою собственную блокировку.

Обратите внимание, что Python.h не включает объявление API TLS, вам необходимо включить pythread.h для использования локального хранения данных в потоке.