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

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

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

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

• Функции инициализации интерпретатора:

  • Py_Initialize()
  • Py_InitializeEx()
  • Py_InitializeFromConfig()
  • Py_BytesMain()
  • Py_Main()
  • функции предварительной инициализации среды выполнения, описанные в разделе Конфигурация инициализации Python

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

  • PyImport_AppendInittab()
  • PyImport_ExtendInittab()
  • PyInitFrozenExtensions()
  • PyMem_SetAllocator()
  • PyMem_SetupDebugHooks()
  • PyObject_SetArenaAllocator()
  • Py_SetProgramName()
  • Py_SetPythonHome()
  • PySys_ResetWarnOptions()
  • функции конфигурации, описанные в разделе Конфигурация инициализации Python

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

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

• Вспомогательные средства:

  • Py_DecodeLocale()
  • функции предоставления сведений о состоянии и вспомогательные функции, описанные в разделе Конфигурация инициализации Python

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

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

• Синхронизация:

  • PyMutex_Lock()
  • PyMutex_Unlock()

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

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

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

int Py_BytesWarningFlag

Этот API сохранён для обратной совместимости: вместо него следует задавать PyConfig.bytes_warning, см. раздел Конфигурация инициализации Python.

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

Задаётся параметром -b.

Устарело с версии 3.12, будет удалено в версии 3.14.

int Py_DebugFlag

Этот API сохранён для обратной совместимости: вместо него следует задавать PyConfig.parser_debug, см. раздел Конфигурация инициализации Python.

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

Задаётся параметром -d и переменной среды PYTHONDEBUG.

Устарело с версии 3.12, будет удалено в версии 3.14.

int Py_DontWriteBytecodeFlag

Этот API сохранён для обратной совместимости: вместо него следует задавать PyConfig.write_bytecode, см. раздел Конфигурация инициализации Python.

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

Задаётся параметром -B и переменной среды PYTHONDONTWRITEBYTECODE.

Устарело с версии 3.12, будет удалено в версии 3.14.

int Py_FrozenFlag

Этот API сохранён для обратной совместимости: вместо него следует задавать PyConfig.pathconfig_warnings, см. раздел Конфигурация инициализации Python.

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

Закрытый флаг, используемый программами _freeze_module и frozenmain.

Устарело с версии 3.12, будет удалено в версии 3.14.

int Py_HashRandomizationFlag

Этот API сохранён для обратной совместимости: вместо него следует задавать PyConfig.hash_seed и PyConfig.use_hash_seed, см. раздел Конфигурация инициализации Python.

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

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

Устарело с версии 3.12, будет удалено в версии 3.14.

int Py_IgnoreEnvironmentFlag

Этот API сохранён для обратной совместимости: вместо него следует задавать PyConfig.use_environment, см. раздел Конфигурация инициализации Python.

Игнорировать все переменные среды PYTHON*, например PYTHONPATH и PYTHONHOME, если они заданы.

Задаётся параметрами -E и -I.

Устарело с версии 3.12, будет удалено в версии 3.14.

int Py_InspectFlag

Этот API сохранён для обратной совместимости: вместо него следует задавать PyConfig.inspect, см. раздел Конфигурация инициализации Python.

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

Задаётся параметром -i и переменной среды PYTHONINSPECT.

Устарело с версии 3.12, будет удалено в версии 3.14.

int Py_InteractiveFlag

Этот API сохранён для обратной совместимости: вместо него следует задавать PyConfig.interactive, см. раздел Конфигурация инициализации Python.

Задаётся параметром -i.

Устарело с версии 3.12, будет удалено в версии 3.15.

int Py_IsolatedFlag

Этот API сохранён для обратной совместимости: вместо него следует задавать PyConfig.isolated, см. раздел Конфигурация инициализации Python.

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

Задаётся параметром -I.

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

Устарело с версии 3.12, будет удалено в версии 3.14.

int Py_LegacyWindowsFSEncodingFlag

Этот API сохранён для обратной совместимости: вместо него следует задавать PyPreConfig.legacy_windows_fs_encoding, см. раздел Конфигурация инициализации Python.

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

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

Подробности см. в PEP 529.

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

Устарело с версии 3.12, будет удалено в версии 3.14.

int Py_LegacyWindowsStdioFlag

Этот API сохранён для обратной совместимости: вместо него следует задавать PyConfig.legacy_windows_stdio, см. раздел Конфигурация инициализации Python.

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

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

Подробности см. в PEP 528.

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

Устарело с версии 3.12, будет удалено в версии 3.14.

int Py_NoSiteFlag

Этот API сохранён для обратной совместимости: вместо него следует задавать PyConfig.site_import, см. раздел Конфигурация инициализации Python.

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

Задаётся параметром -S.

Устарело с версии 3.12, будет удалено в версии 3.14.

int Py_NoUserSiteDirectory

Этот API сохранён для обратной совместимости: вместо него следует задавать PyConfig.user_site_directory, см. раздел Конфигурация инициализации Python.

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

Задаётся параметрами -s и -I, а также переменной среды PYTHONNOUSERSITE.

Устарело с версии 3.12, будет удалено в версии 3.14.

int Py_OptimizeFlag

Этот API сохранён для обратной совместимости: вместо него следует задавать PyConfig.optimization_level, см. раздел Конфигурация инициализации Python.

Задаётся параметром -O и переменной среды PYTHONOPTIMIZE.

Устарело с версии 3.12, будет удалено в версии 3.14.

int Py_QuietFlag

Этот API сохранён для обратной совместимости: вместо него следует задавать PyConfig.quiet, см. раздел Конфигурация инициализации Python.

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

Задаётся параметром -q.

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

Устарело с версии 3.12, будет удалено в версии 3.14.

int Py_UnbufferedStdioFlag

Этот API сохранён для обратной совместимости: вместо него следует задавать PyConfig.buffered_stdio, см. раздел Конфигурация инициализации Python.

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

Задаётся параметром -u и переменной среды PYTHONUNBUFFERED.

Устарело с версии 3.12, будет удалено в версии 3.14.

int Py_VerboseFlag

Этот API сохранён для обратной совместимости: вместо него следует задавать PyConfig.verbose, см. раздел Конфигурация инициализации Python.

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

Задаётся параметром -v и переменной среды PYTHONVERBOSE.

Устарело с версии 3.12, будет удалено в версии 3.14.

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

void Py_Initialize()

Часть стабильного ABI.

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

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

Чтобы настроить конфигурацию инициализации Python, используйте Py_InitializeFromConfig().

Примечание

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

void Py_InitializeEx(int initsigs)

Часть стабильного ABI.

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

Чтобы настроить конфигурацию инициализации Python, используйте Py_InitializeFromConfig().

PyStatus Py_InitializeFromConfig(const PyConfig *config)

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

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

int Py_IsInitialized()

Часть стабильного ABI.

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

int Py_IsFinalizing()

Часть стабильного ABI начиная с версии 3.13.

Возвращает true (ненулевое значение), если основной интерпретатор Python завершает работу. В противном случае возвращает false (нулевое значение).

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

int Py_FinalizeEx()

Часть стабильного ABI начиная с версии 3.6.

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

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

Обычно возвращаемое значение — 0. Если при завершении работы произошли ошибки (например, при сбросе буферизованных данных), возвращается -1.

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

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

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

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

void Py_Finalize()

Часть стабильного ABI.

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

int Py_BytesMain(int argc, char **argv)

Часть стабильного ABI начиная с версии 3.8.

Похожа на Py_Main(), но argv представляет собой массив байтовых строк, что позволяет вызывающему приложению поручить декодирование текста среде выполнения CPython.

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

int Py_Main(int argc, wchar_t **argv)

Часть стабильного ABI.

Главная программа стандартного интерпретатора, выполняющая полный цикл инициализации и завершения работы, а также дополнительные действия для чтения параметров конфигурации из окружения и командной строки и последующего выполнения __main__ в соответствии с разделом Командная строка.

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

Параметры argc и argv аналогичны параметрам, передаваемым функции main() программы на C, за исключением того, что элементы argv сначала преобразуются в wchar_t с помощью Py_DecodeLocale(). Также важно отметить, что элементы списка аргументов могут быть изменены так, чтобы указывать на другие строки, а не на переданные (содержимое строк, на которые указывает список аргументов, при этом не изменяется).

Если список аргументов не соответствует допустимой командной строке Python, возвращается 2, в противном случае возвращается то же значение, что и у Py_RunMain().

С точки зрения API конфигурации среды выполнения CPython, описанных в разделе конфигурации среды выполнения (без учета обработки ошибок), Py_Main приблизительно эквивалентна следующему:

PyConfig config;
PyConfig_InitPythonConfig(&config);
PyConfig_SetArgv(&config, argc, argv);
Py_InitializeFromConfig(&config);
PyConfig_Clear(&config);

Py_RunMain();

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

int Py_RunMain(void)

Выполняет главный модуль в полностью сконфигурированной среде выполнения CPython.

Выполняет команду (PyConfig.run_command), скрипт (PyConfig.run_filename) или модуль (PyConfig.run_module), указанный в командной строке или конфигурации. Если ни одно из этих значений не задано, запускает интерактивную командную строку Python (REPL), используя глобальное пространство имен модуля __main__.

Если PyConfig.inspect не задан (значение по умолчанию), возвращаемым значением будет 0, если интерпретатор завершился нормально (то есть без исключения), код завершения необработанного исключения SystemExit или 1 для любого другого необработанного исключения.

Если задан PyConfig.inspect (например, при использовании параметра -i), после завершения работы интерпретатора функция не возвращает управление, а продолжает выполнение в интерактивной командной строке Python (REPL), используя глобальное пространство имен модуля __main__. Если интерпретатор завершился с исключением, оно немедленно вызывается в сеансе REPL. Тогда возвращаемое значение функции определяется способом завершения сеанса REPL: 0, 1 или кодом завершения исключения SystemExit, как описано выше.

Эта функция всегда завершает работу интерпретатора Python перед возвратом.

Пример настроенной версии Python, которая всегда работает в изолированном режиме с помощью Py_RunMain(), приведен в разделе Конфигурация Python.

int PyUnstable_AtExit(PyInterpreterState *interp, void (*func)(void*), void *data)

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

Регистрирует функцию обратного вызова atexit для целевого интерпретатора interp. Она похожа на Py_AtExit(), но принимает явные параметры: интерпретатор и указатель на данные, передаваемые функции обратного вызова.

Для interp должна быть захвачена блокировка GIL.

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

Параметры всего процесса

void Py_SetProgramName(const wchar_t *name)

Часть стабильного ABI.

Этот API сохранён для обратной совместимости: вместо него следует задавать PyConfig.program_name, см. Конфигурация инициализации Python.

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

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

Устарело с версии 3.11.

wchar_t *Py_GetProgramName()

Часть стабильного ABI.

Возвращает имя программы, заданное с помощью PyConfig.program_name, или значение по умолчанию. Возвращённая строка указывает на статическую область памяти; вызывающий код не должен изменять её значение.

Эту функцию не следует вызывать до Py_Initialize(), иначе она возвращает NULL.

Изменено в версии 3.10: Теперь возвращает NULL, если вызвана до Py_Initialize().

Устарело с версии 3.13, будет удалено в версии 3.15: Вместо этого используйте sys.executable.

wchar_t *Py_GetPrefix()

Часть стабильного ABI.

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

Эту функцию не следует вызывать до Py_Initialize(), иначе она возвращает NULL.

Изменено в версии 3.10: Теперь возвращает NULL, если вызвана до Py_Initialize().

Устарело с версии 3.13, будет удалено в версии 3.15: Вместо этого используйте sys.base_prefix или sys.prefix, если требуется поддержка виртуальных окружений.

wchar_t *Py_GetExecPrefix()

Часть стабильного ABI.

Возвращает exec-префикс для установленных платформозависимых файлов. Он определяется по ряду сложных правил на основе имени программы, заданного с помощью PyConfig.program_name, и некоторых переменных среды; например, если имя программы — '/usr/local/bin/python', exec-префикс — '/usr/local'. Возвращённая строка указывает на статическую область памяти; вызывающий код не должен изменять её значение. Это соответствует переменной exec_prefix в корневом Makefile и аргументу --exec-prefix скрипта configure во время сборки. Это значение доступно коду Python как sys.base_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 отдельной файловой системой для каждой платформы.

Эту функцию не следует вызывать до Py_Initialize(), иначе она возвращает NULL.

Изменено в версии 3.10: Теперь возвращает NULL, если вызвана до Py_Initialize().

Устарело с версии 3.13, будет удалено в версии 3.15: Вместо этого используйте sys.base_exec_prefix или sys.exec_prefix, если требуется поддержка виртуальных окружений.

wchar_t *Py_GetProgramFullPath()

Часть стабильного ABI.

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

Эту функцию не следует вызывать до Py_Initialize(), иначе она возвращает NULL.

Изменено в версии 3.10: Теперь возвращает NULL, если вызвана до Py_Initialize().

Устарело с версии 3.13, будет удалено в версии 3.15: Вместо этого используйте sys.executable.

wchar_t *Py_GetPath()

Часть стабильного ABI.

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

Эту функцию не следует вызывать до Py_Initialize(), иначе она возвращает NULL.

Изменено в версии 3.10: Теперь возвращает NULL, если вызвана до Py_Initialize().

Устарело с версии 3.13, будет удалено в версии 3.15: Вместо этого используйте sys.path.

const char *Py_GetVersion()

Часть стабильного ABI.

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

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

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

См. также константу Py_Version.

const char *Py_GetPlatform()

Часть стабильного ABI.

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

const char *Py_GetCopyright()

Часть стабильного ABI.

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

'Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam'

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

const char *Py_GetCompiler()

Часть стабильного ABI.

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

"[GCC 2.7.2.2]"

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

const char *Py_GetBuildInfo()

Часть стабильного ABI.

Возвращает сведения о порядковом номере, а также дате и времени сборки текущего экземпляра интерпретатора Python, например:

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

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

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

Часть стабильного ABI.

Этот API сохранён для обратной совместимости: вместо него следует задавать PyConfig.argv, PyConfig.parse_argv и PyConfig.safe_path, см. Конфигурация инициализации Python.

Задаёт 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_t*.

См. также элементы PyConfig.orig_argv и PyConfig.argv в разделе Конфигурация инициализации Python.

Примечание

Рекомендуется, чтобы приложения, встраивающие интерпретатор 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.

Устарело с версии 3.11.

void PySys_SetArgv(int argc, wchar_t **argv)

Часть стабильного ABI.

Этот API сохранён для обратной совместимости: вместо него следует задавать PyConfig.argv и PyConfig.parse_argv, см. Конфигурация инициализации Python.

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

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

См. также элементы PyConfig.orig_argv и PyConfig.argv в разделе Конфигурация инициализации Python.

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

Устарело с версии 3.11.

void Py_SetPythonHome(const wchar_t *home)

Часть стабильного ABI.

Этот API сохранён для обратной совместимости: вместо него следует задавать PyConfig.home, см. Конфигурация инициализации Python.

Задаёт каталог «home» по умолчанию, то есть расположение стандартных библиотек Python. Значение строки аргумента описано в PYTHONHOME.

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

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

Устарело с версии 3.11.

wchar_t *Py_GetPythonHome()

Часть стабильного ABI.

Возвращает «home» по умолчанию, то есть значение, заданное с помощью PyConfig.home, либо значение переменной среды PYTHONHOME, если она задана.

Эту функцию не следует вызывать до Py_Initialize(), иначе она возвращает NULL.

Изменено в версии 3.10: Теперь возвращает NULL, если вызвана до Py_Initialize().

Устарело с версии 3.13, будет удалено в версии 3.15: Вместо этого используйте PyConfig.home или переменную среды PYTHONHOME.

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

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

Поэтому действует правило: работать с объектами Python или вызывать функции Python/C API может только поток, захвативший GIL. Чтобы имитировать параллельное выполнение, интерпретатор регулярно пытается переключать потоки (см. 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(). Создавать и уничтожать их можно с помощью следующих функций:

type PyInterpreterConfig

Структура, содержащая большинство параметров настройки субинтерпретатора. Её значения используются только в Py_NewInterpreterFromConfig() и никогда не изменяются средой выполнения.

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

Поля структуры:

int use_main_obmalloc

Если значение равно 0, субинтерпретатор будет использовать собственное состояние распределителя памяти «объектов». В противном случае он будет использовать (совместно с главным интерпретатором) его состояние.

Если значение равно 0, то check_multi_interp_extensions должно быть равно 1 (не нулю). Если значение равно 1, то gil не должно быть равно PyInterpreterConfig_OWN_GIL.

int allow_fork

Если значение равно 0, среда выполнения не будет поддерживать создание ответвления процесса в каком-либо потоке, где в данный момент активен субинтерпретатор. В противном случае создание ответвлений не ограничено.

Обратите внимание, что модуль subprocess продолжает работать, даже если создание ответвлений запрещено.

int allow_exec

Если значение равно 0, среда выполнения не будет поддерживать замену текущего процесса посредством exec (например, os.execv()) в каком-либо потоке, где в данный момент активен субинтерпретатор. В противном случае использование exec не ограничено.

Обратите внимание, что модуль subprocess продолжает работать, даже если exec запрещён.

int allow_threads

Если значение равно 0, модуль threading субинтерпретатора не будет создавать потоки. В противном случае потоки разрешены.

int allow_daemon_threads

Если значение равно 0, модуль threading субинтерпретатора не будет создавать потоки-демоны. В противном случае потоки-демоны разрешены (если allow_threads не равно нулю).

int check_multi_interp_extensions

Если значение равно 0, в любом потоке, где в данный момент активен субинтерпретатор, можно импортировать все модули расширений, включая устаревшие модули (с однофазной инициализацией). В противном случае можно импортировать только модули расширений с многофазной инициализацией (см. PEP 489). (См. также Py_mod_multiple_interpreters.)

Значение должно быть 1 (не нулём), если use_main_obmalloc равно 0.

int gil

Этот параметр определяет работу GIL субинтерпретатора. Он может принимать одно из следующих значений:

PyInterpreterConfig_DEFAULT_GIL

Использовать значение по умолчанию (PyInterpreterConfig_SHARED_GIL).

PyInterpreterConfig_SHARED_GIL

Использовать GIL главного интерпретатора (совместно с ним).

PyInterpreterConfig_OWN_GIL

Использовать собственный GIL субинтерпретатора.

Если значение равно PyInterpreterConfig_OWN_GIL, то PyInterpreterConfig.use_main_obmalloc должно быть равно 0.

PyStatus Py_NewInterpreterFromConfig(PyThreadState **tstate_p, const PyInterpreterConfig *config)

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

Указанный параметр config задаёт параметры инициализации интерпретатора.

В случае успеха параметру tstate_p будет присвоено состояние первого потока, созданного в новом субинтерпретаторе. Это состояние потока создаётся в текущем состоянии потока. Обратите внимание, что фактический поток не создаётся; см. обсуждение состояний потоков ниже. Если создать новый интерпретатор не удастся, параметру tstate_p будет присвоено значение NULL; исключение не устанавливается, поскольку состояние исключения хранится в текущем состоянии потока, а текущее состояние потока может отсутствовать.

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

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

Субинтерпретаторы работают наиболее эффективно, когда изолированы друг от друга и доступ к некоторым функциям ограничен:

PyInterpreterConfig config = {
    .use_main_obmalloc = 0,
    .allow_fork = 0,
    .allow_exec = 0,
    .allow_threads = 1,
    .allow_daemon_threads = 0,
    .check_multi_interp_extensions = 1,
    .gil = PyInterpreterConfig_OWN_GIL,
};
PyThreadState *tstate = NULL;
PyStatus status = Py_NewInterpreterFromConfig(&tstate, &config);
if (PyStatus_Exception(status)) {
    Py_ExitStatusException(status);
}

Обратите внимание, что конфигурация используется лишь непродолжительное время и не изменяется. Во время инициализации значения конфигурации преобразуются в различные значения PyInterpreterState. Копия конфигурации, доступная только для чтения, может храниться внутри PyInterpreterState.

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

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

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

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

PyThreadState *Py_NewInterpreter(void)

Часть стабильного ABI.

Создаёт новый субинтерпретатор. По сути, это лишь обёртка над Py_NewInterpreterFromConfig() с конфигурацией, сохраняющей прежнее поведение. В результате создаётся неизолированный субинтерпретатор, который использует GIL главного интерпретатора совместно с ним, разрешает создание ответвлений и exec, разрешает потоки-демоны и модули с однофазной инициализацией.

void Py_EndInterpreter(PyThreadState *tstate)

Часть стабильного ABI.

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

Py_FinalizeEx() уничтожит все субинтерпретаторы, которые к тому моменту не были явно уничтожены.

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

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

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

Часть стабильного ABI.

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

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

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

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

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

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

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

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

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

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

Изменено в версии 3.12: Теперь эта функция всегда планирует выполнение func в главном интерпретаторе.

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

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

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

typedef 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 (но не функции профилирования), когда сообщается о событии номера строки. Для кадра это событие можно отключить, задав значение 0 атрибуту f_trace_lines этого кадра.

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 (но не функций профилирования), когда собирается выполниться новая инструкция байт-кода. По умолчанию это событие не генерируется: для его включения необходимо явно задать значение 1 атрибуту f_trace_opcodes кадра.

void PyEval_SetProfile(Py_tracefunc func, PyObject *obj)

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

См. также функцию sys.setprofile().

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

void PyEval_SetProfileAllThreads(Py_tracefunc func, PyObject *obj)

Подобно PyEval_SetProfile(), но устанавливает функцию профилирования во всех работающих потоках текущего интерпретатора, а не только в текущем потоке.

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

Как и PyEval_SetProfile(), эта функция игнорирует исключения, возникающие при установке функций профилирования во всех потоках.

void PyEval_SetTrace(Py_tracefunc func, PyObject *obj)

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

См. также функцию sys.settrace().

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

void PyEval_SetTraceAllThreads(Py_tracefunc func, PyObject *obj)

Подобно PyEval_SetTrace(), но устанавливает функцию трассировки во всех работающих потоках текущего интерпретатора, а не только в текущем потоке.

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

Как и PyEval_SetTrace(), эта функция игнорирует исключения, возникающие при установке функций трассировки во всех потоках.

Трассировка ссылок

typedef int (*PyRefTracer)(PyObject*, int event, void *data)

Тип функции трассировки, зарегистрированной с помощью PyRefTracer_SetTracer(). Первый параметр — только что созданный объект Python (если для event задано значение PyRefTracer_CREATE) или объект, который собираются уничтожить (если для event задано значение PyRefTracer_DESTROY). Аргумент data — это непрозрачный указатель, переданный при вызове PyRefTracer_SetTracer().

int PyRefTracer_CREATE

Значение параметра event функций PyRefTracer, когда создан объект Python.

int PyRefTracer_DESTROY

Значение параметра event функций PyRefTracer, когда объект Python уничтожен.

int PyRefTracer_SetTracer(PyRefTracer tracer, void *data)

Регистрирует функцию трассировки ссылок. Функция вызывается при создании нового объекта Python или перед уничтожением объекта. Если указан data, он должен быть непрозрачным указателем, который будет передан при вызове функции трассировки. При успешном выполнении возвращает 0. В случае ошибки устанавливает исключение и возвращает -1.

Обратите внимание: функции трассировки не должны создавать объекты Python, иначе вызов станет реентерабельным. Трассировщик также не должен сбрасывать существующее исключение или устанавливать исключение. При каждом вызове функции трассировки будет удерживаться GIL.

При вызове этой функции необходимо удерживать GIL.

PyRefTracer PyRefTracer_GetTracer(void **data)

Возвращает зарегистрированную функцию трассировки ссылок и значение непрозрачного указателя данных, зарегистрированного при вызове PyRefTracer_SetTracer(). Если трассировщик не зарегистрирован, эта функция возвращает NULL и устанавливает для указателя data значение NULL.

При вызове этой функции необходимо удерживать 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 уровня C в CPython похожи на API, предлагаемые pthreads и Windows: используйте ключ потока и функции, чтобы связать значение void* с каждым потоком.

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

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

Примитивы синхронизации

C-API предоставляет базовую блокировку взаимного исключения.

type PyMutex

Блокировка взаимного исключения. PyMutex следует инициализировать нулём, чтобы представить состояние разблокировки. Например:

PyMutex mutex = {0};

Экземпляры PyMutex не следует копировать или перемещать. Значимы как содержимое, так и адрес PyMutex, поэтому оно должно оставаться в фиксированном, доступном для записи месте в памяти.

Примечание

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

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

void PyMutex_Lock(PyMutex *m)

Блокирует мьютекс m. Если другой поток уже заблокировал его, вызывающий поток будет ожидать, пока мьютекс не будет разблокирован. Во время ожидания поток временно освобождает GIL, если он захвачен.

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

void PyMutex_Unlock(PyMutex *m)

Разблокирует мьютекс m. Мьютекс должен быть заблокирован — в противном случае функция вызовет фатальную ошибку.

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

static PyObject *
set_field(MyObject *self, PyObject *value)
{
   Py_BEGIN_CRITICAL_SECTION(self);
   Py_SETREF(self->field, Py_XNewRef(value));
   Py_END_CRITICAL_SECTION();
   Py_RETURN_NONE;
}