Инициализация, Заключительные действия и Потоки

Перед инициализацией 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.

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.

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

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

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

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

Примечание

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

void Py_InitializeEx(int initsigs)

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

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

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

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 без перезапуска самого приложения. Приложение, которое загрузило интерпретатор Python из динамически загружаемой библиотеки (или DLL), может захотеть освободить всю память, выделенную Python, перед разгрузкой DLL. Во время поиска утечек памяти в приложении разработчик может захотеть освободить всю память, выделенную Python, перед выходом из приложения.

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

Вызывает событие аудита 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(). Также важно отметить, что записи списка аргументов могут быть изменены для указания на строки, отличные от переданных (однако содержимое строк, на которые указывают записи списка аргументов, не изменяется).

Возвращаемое значение будет 0 , если интерпретатор завершается нормально (т.е. без исключения), 1 , если интерпретатор завершается из-за исключения, или 2 , если список аргументов не представляет собой допустимую командную строку Python.

Обратите внимание, что если исключение SystemExit не обрабатывается, эта функция не вернёт 1, а завершит процесс, при условии, что Py_InspectFlag не установлено. Если Py_InspectFlag установлено, выполнение перейдёт к интерактивному приглашению Python, в котором второй необработанный SystemExit по-прежнему завершит процесс, а любые другие способы завершения установят возвращаемое значение, как описано выше.

С точки зрения 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 , если интерпретатор завершается нормально (то есть без повышения исключения), или 1 , если интерпретатор завершается из-за исключения. Если необработанное исключение SystemExit возникает, функция немедленно завершит процесс вместо возврата 1.

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

Эта функция всегда завершает интерпретатор Python независимо от того, возвращает ли она значение или немедленно завершает процесс из-за необработанного исключения SystemExit.

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

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

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_*.

Устарело начиная с версии 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_*.

См. также члены 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.

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

См. также 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 не изменит содержимое этого хранилища.

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

Устарело начиная с версии 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. Без блокировки даже простейшие операции могут привести к проблемам в многопоточной программе: например, когда два потока одновременно увеличивают счётчик ссылок одного и того же объекта, счётчик ссылок может быть увеличен только один раз вместо двух.

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

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

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

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

PyThreadState *_save;

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

PyGILState_STATE gstate;
gstate = PyGILState_Ensure();

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

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

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

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

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

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

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

Как и все другие функции API Python/C, блокировка глобального интерпретатора должна быть захвачена перед вызовом этой функции и все еще захвачена, когда она возвращается. Аналогично, текущее состояние потока должно быть установлено при входе. При успехе, возвращенное состояние потока будет установлено как текущее. Если подинтерпретатор создается со своим собственным 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 основного интерпретатора, допускает fork/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 теперь запланирована для вызова из подинтерпретатора, а не из основного интерпретатора. Каждый подинтерпретатор теперь имеет свой собственный список запланированных вызовов.

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

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

Отслеживание ссылок

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). C-уровневые API CPython похожи на те, что предлагаются 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;
}