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

Перед инициализацией 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 и Mac OS X, ';' в Windows. Возвращаемая строка указывает на статическое хранилище; вызывающий код не должен изменять ее значение. Список sys.path инициализируется этим значением при запуске интерпретатора; он может (и обычно изменяется) позже, чтобы изменить путь поиска для загрузки модулей.

void Py_SetPath(const wchar_t *)

Задает стандартный путь поиска модулей. Если эта функция вызывается до Py_Initialize(), то Py_GetPath() не будет пытаться вычислить стандартный путь поиска, а использует предоставленный вместо этого. Это полезно, если Python встроен приложением, которое полностью знает местоположение всех модулей. Компоненты пути должны быть разделены символом разделителя, зависящим от платформы, который составляет ':' в Unix и Mac OS X, ';' в 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'. В Mac OS X — '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 pointer.

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

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

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

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

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

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

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

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

Добавлена в версии 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 при сообщении о новом вызове функции или метода, или новом входе в генератор. Обратите внимание, что создание итератора для функции генератора не сообщается, так как нет передачи управления в байт-код Python в соответствующем фрейме.

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.

void PyEval_SetTrace(Py_tracefunc func, PyObject *obj)

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

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

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

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 для использования локального хранения данных для потоков.