Инициализация, финализация и потоки¶Initialization, Finalization, and Threads

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

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

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

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

  • Py_Initialize()

  • Py_InitializeEx()

  • Py_InitializeFromConfig()

  • Py_BytesMain()

  • Py_Main()

  • функции предварительной инициализации среды выполнения, описанные в Python Initialization Configuration

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

  • PyImport_AppendInittab()

  • PyImport_ExtendInittab()

  • PyInitFrozenExtensions()

  • PyMem_SetAllocator()

  • PyMem_SetupDebugHooks()

  • PyObject_SetArenaAllocator()

  • Py_SetProgramName()

  • Py_SetPythonHome()

  • PySys_ResetWarnOptions()

  • функции конфигурации, описанные в Python Initialization Configuration

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

  • Py_IsInitialized()

  • PyMem_GetAllocator()

  • PyObject_GetArenaAllocator()

  • Py_GetBuildInfo()

  • Py_GetCompiler()

  • Py_GetCopyright()

  • Py_GetPlatform()

  • Py_GetVersion()

  • Py_IsInitialized()

• Утилиты:

  • Py_DecodeLocale()

  • функции сообщения о состоянии и утилиты, описанные в Python Initialization Configuration

• Распределители памяти:

  • PyMem_RawMalloc()

  • PyMem_RawRealloc()

  • PyMem_RawCalloc()

  • PyMem_RawFree()

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

  • PyMutex_Lock()

  • PyMutex_Unlock()

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

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

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

int Py_BytesWarningFlag¶

Этот API сохранён для обратной совместимости: вместо него следует использовать PyConfig.bytes_warning. См. Python Initialization Configuration.

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

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

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

int Py_DebugFlag¶

Этот API сохранён для обратной совместимости: вместо него следует использовать PyConfig.parser_debug. См. Python Initialization Configuration.

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

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

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

int Py_DontWriteBytecodeFlag¶

Этот API сохранён для обратной совместимости: вместо него следует использовать PyConfig.write_bytecode. См. Python Initialization Configuration.

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

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

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

int Py_FrozenFlag¶

Этот API сохранён для обратной совместимости: следует использовать настройку PyConfig.pathconfig_warnings; см. Python Initialization Configuration.

Подавляет сообщения об ошибках при вычислении пути поиска модулей в 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 Initialization Configuration.

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

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

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

int Py_InspectFlag¶

Этот API сохранён для обратной совместимости: следует использовать настройку PyConfig.inspect; см. Python Initialization Configuration.

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

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

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

int Py_InteractiveFlag¶

Этот API сохранён для обратной совместимости: следует использовать настройку PyConfig.interactive; см. Python Initialization Configuration.

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

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

int Py_IsolatedFlag¶

Этот API сохранён для обратной совместимости: следует использовать настройку PyConfig.isolated; см. Python Initialization Configuration.

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

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

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

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

int Py_LegacyWindowsFSEncodingFlag¶

Этот API сохранён для обратной совместимости: следует использовать настройку PyPreConfig.legacy_windows_fs_encoding; см. Python Initialization Configuration.

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

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

См. PEP 529 для подробностей.

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

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

int Py_LegacyWindowsStdioFlag¶

Этот API сохранён для обратной совместимости: следует использовать настройку PyConfig.legacy_windows_stdio; см. Python Initialization Configuration.

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

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

См. PEP 528 для подробностей.

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

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

int Py_NoSiteFlag¶

Этот API сохранён для обратной совместимости: следует использовать настройку PyConfig.site_import; см. Python Initialization Configuration.

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

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

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

int Py_NoUserSiteDirectory¶

Этот API сохранён для обратной совместимости: следует использовать настройку PyConfig.user_site_directory; см. Python Initialization Configuration.

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

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

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

int Py_OptimizeFlag¶

Этот API сохранён для обратной совместимости: следует использовать настройку PyConfig.optimization_level; см. Python Initialization Configuration.

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

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

int Py_QuietFlag¶

Этот API сохранён для обратной совместимости: вместо него следует использовать PyConfig.quiet. См. Python Initialization Configuration.

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

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

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

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

int Py_UnbufferedStdioFlag¶

Этот API сохранён для обратной совместимости: вместо него следует использовать PyConfig.buffered_stdio. См. Python Initialization Configuration.

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

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

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

int Py_VerboseFlag¶

Этот API сохранён для обратной совместимости: вместо него следует использовать PyConfig.verbose. См. Python Initialization Configuration.

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

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

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

Инициализация и завершение работы интерпретатора¶Initializing and finalizing the interpreter

void Py_Initialize()¶

Часть Stable ABI.

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

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

Используйте Py_InitializeFromConfig() для настройки конфигурации инициализации Python.

Примечание

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

void Py_InitializeEx(int initsigs)¶

Часть Stable ABI.

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

Используйте Py_InitializeFromConfig() для настройки конфигурации инициализации Python.

PyStatus Py_InitializeFromConfig(const PyConfig *config)¶

Инициализирует Python из конфигурации config, как описано в Initialization with PyConfig.

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

int Py_IsInitialized()¶

Часть Stable ABI.

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

int Py_IsFinalizing()¶

Часть Stable ABI, начиная с версии 3.13.

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

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

int Py_FinalizeEx()¶

Часть Stable 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()¶

Часть Stable ABI.

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

int Py_BytesMain(int argc, char **argv)¶

Часть Stable ABI с версии 3.8.

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

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

int Py_Main(int argc, wchar_t **argv)¶

Часть Stable ABI.

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

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

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

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

С точки зрения API конфигурации среды выполнения CPython, описанных в разделе runtime configuration (и без учёта обработки ошибок), 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 для примера пользовательской сборки Python, которая всегда работает в изолированном режиме с использованием Py_RunMain().

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

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

Регистрирует колбэк atexit для целевого интерпретатора interp. Это аналогично Py_AtExit(), но принимает явный указатель на интерпретатор и данные для колбэка.

GIL должна удерживаться для interp.

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

Общепроцессные параметры¶Process-wide parameters

void Py_SetProgramName(const wchar_t *name)¶

Часть Stable ABI.

Этот API сохранён для обратной совместимости: вместо него следует использовать PyConfig.program_name. См. Python Initialization Configuration.

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

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

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

wchar_t *Py_GetProgramName()¶

Часть Stable ABI.

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

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

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

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

wchar_t *Py_GetPrefix()¶

Часть Stable 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()¶

Часть Stable ABI.

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

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

Вообще говоря, платформа – это комбинация семейств аппаратного и программного обеспечения; например, машины Sparc под управлением ОС Solaris 2.x считаются одной платформой, машины Intel под Solaris 2.x – другой, а машины Intel под Linux – третьей. Разные основные версии одной и той же ОС обычно также образуют разные платформы. Операционные системы, отличные от Unix, – это отдельная история; стратегии установки на этих системах настолько различаются, что префикс и exec-prefix не имеют смысла и устанавливаются в пустую строку. Обратите внимание: скомпилированные файлы байт-кода 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()¶

Часть Stable 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()¶

Часть Stable 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()¶

Часть Stable 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()¶

Часть Stable ABI.

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

const char *Py_GetCopyright()¶

Часть Stable ABI.

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

'Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam'

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

const char *Py_GetCompiler()¶

Часть Stable ABI.

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

"[GCC 2.7.2.2]"

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

const char *Py_GetBuildInfo()¶

Часть Stable ABI.

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

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

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

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

Часть Stable ABI.

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

Устанавливает 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 Initialization Configuration.

Примечание

Приложениям, встраивающим интерпретатор 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)¶

Часть Stable ABI.

Этот API сохранён для обратной совместимости: вместо него следует использовать PyConfig.argv и PyConfig.parse_argv. См. Python Initialization Configuration.

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

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

См. также члены PyConfig.orig_argv и PyConfig.argv структуры Python Initialization Configuration.

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

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

void Py_SetPythonHome(const wchar_t *home)¶

Часть Stable ABI.

Этот API сохранён для обратной совместимости: вместо него следует использовать PyConfig.home. См. Python Initialization Configuration.

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

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

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

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

wchar_t *Py_GetPythonHome()¶

Часть Stable ABI.

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

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

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

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

Состояние потока и глобальная блокировка интерпретатора¶Thread State and the Global Interpreter Lock

Интерпретатор 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();

/* Выполнить действия Python здесь. */
result = CallSomeFunction();
/* вычислить результат или обработать исключение */

/* Освободить поток. После этой точки API Python не допускается. */
PyGILState_Release(gstate);

Поддержка под-интерпретаторов¶Sub-interpreter support

Хотя в большинстве случаев достаточно встроить один интерпретатор 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);
}

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

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

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

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

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

PyThreadState *Py_NewInterpreter(void)¶

Часть Stable ABI.

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

void Py_EndInterpreter(PyThreadState *tstate)¶

Часть Stable ABI.

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

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

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

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

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

Часть Stable ABI.

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

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

• на границе байткода;

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

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

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

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

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

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

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

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

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

int Py_MakePendingCalls(void)¶

Часть Stable ABI.

Выполняет все отложенные вызовы. Обычно это выполняется автоматически интерпретатором.

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

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

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

Изменено в версии 3.12: Эта функция выполняет отложенные вызовы только в основном интерпретаторе.

Профилирование и трассировка¶Profiling and Tracing

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

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

Трассировка ссылок¶Reference tracing

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.

Поддержка расширенного отладчика¶Advanced Debugger Support

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

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.

Поддержка локального хранилища потоков¶Thread Local Storage Support

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

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

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

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

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;
}

API потоков операционной системы¶Operating System Thread APIs

PYTHREAD_INVALID_THREAD_ID¶

Страж-значение для недопустимого идентификатора потока.

В настоящее время эквивалентно (unsigned long)-1.

unsigned long PyThread_start_new_thread(void (*func)(void*), void *arg)¶

Часть Stable ABI.

Запускает функцию func в новом потоке с аргументом arg. Полученный поток не предназначен для ожидания завершения.

func не должна быть NULL, но arg может быть NULL.

При успехе эта функция возвращает идентификатор нового потока; при неудаче возвращает PYTHREAD_INVALID_THREAD_ID.

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

unsigned long PyThread_get_thread_ident(void)¶

Часть Stable ABI.

Возвращает идентификатор текущего потока, который никогда не будет равен нулю.

Эта функция не может завершиться ошибкой, и вызывающему не нужно удерживать GIL.

См. также

threading.get_ident()

PyObject *PyThread_GetInfo(void)¶

Часть Stable ABI начиная с версии 3.3.

Получает общую информацию о текущем потоке в виде объекта структурной последовательности. Эта информация доступна как sys.thread_info в Python.

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

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

PY_HAVE_THREAD_NATIVE_ID¶

Этот макрос определён, когда система поддерживает нативные идентификаторы потоков.

unsigned long PyThread_get_thread_native_id(void)¶

Часть Stable ABI на платформах с нативными идентификаторами потоков.

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

Эта функция доступна, только если определён PY_HAVE_THREAD_NATIVE_ID.

Эта функция не может завершиться ошибкой, и вызывающему не нужно удерживать GIL.

См. также

threading.get_native_id()

void PyThread_exit_thread(void)¶

Часть Stable ABI.

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

Эту функцию безопасно вызывать, только если все функции в полном стеке вызовов написаны так, чтобы допускать это безопасно.

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

Если текущая система использует потоки POSIX (также известные как «pthreads»), эта функция вызывает pthread_exit(3), которая пытается развернуть стек и вызвать деструкторы C++ в некоторых реализациях libc. Однако, если достигается функция noexcept, это может завершить процесс. Другие системы, такие как macOS, выполняют развёртывание.

В Windows эта функция вызывает _endthreadex(), которая уничтожает поток без вызова деструкторов C++.

В любом случае существует риск повреждения стека потока.

void PyThread_init_thread(void)¶

Часть Stable ABI.

Инициализирует API PyThread*. Python выполняет эту функцию автоматически, поэтому нет особой необходимости вызывать её из расширяющего модуля.

int PyThread_set_stacksize(size_t size)¶

Часть Stable ABI.

Устанавливает размер стека текущего потока в size байт.

Эта функция возвращает 0 при успехе, -1, если size некорректен, или -2, если система не поддерживает изменение размера стека. Эта функция не устанавливает исключения.

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

size_t PyThread_get_stacksize(void)¶

Часть Stable ABI.

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

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