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

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

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

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

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

В большинстве случаев это достаточно просто. Большая часть кода, работающего с глобальной блокировкой интерпретатора, имеет следующую простую структуру:

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

Макрос Py_BEGIN_ALLOW_THREADS открывает новый блок и объявляет скрытую локальную переменную; макрос Py_END_ALLOW_THREADS закрывает блок. Ещё одно преимущество использования этих двух макросов в том, что при компиляции Python без поддержки потоков они определены пустыми, что избавляет от манипуляций с состоянием потока и GIL.

Когда поддержка потоков включена, указанный выше блок раскрывается в следующий код:

PyThreadState *_save;

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

Используя ещё более низкоуровневые примитивы, можно получить примерно тот же эффект следующим образом:

PyThreadState *_save;

_save = PyThreadState_Swap(NULL);
PyEval_ReleaseLock();
...Do some blocking I/O operation...
PyEval_AcquireLock();
PyThreadState_Swap(_save);

Существуют некоторые тонкие различия; в частности, PyEval_RestoreThread() сохраняет и восстанавливает значение глобальной переменной errno, поскольку манипуляции с блокировкой не гарантируют, что errno останется нетронутым. Кроме того, если поддержка потоков отключена, PyEval_SaveThread() и PyEval_RestoreThread() не управляют GIL; в этом случае PyEval_ReleaseLock() и PyEval_AcquireLock() недоступны. Это сделано для того, чтобы динамически загружаемые расширения, скомпилированные с включённой поддержкой потоков, могли быть загружены интерпретатором, скомпилированным с отключённой поддержкой потоков.

Глобальная блокировка интерпретатора используется для защиты указателя на текущее состояние потока. При отпускании блокировки и сохранении состояния потока указатель на текущее состояние потока должен быть получен до того, как блокировка будет отпущена (поскольку другой поток может немедленно захватить блокировку и сохранить своё собственное состояние потока в глобальной переменной). И наоборот, при захвате блокировки и восстановлении состояния потока блокировка должна быть захвачена до сохранения указателя на состояние потока.

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

Начиная с версии 2.3, потоки могут использовать функции PyGILState_*(), чтобы автоматически выполнять все вышеперечисленные действия. Типичный подход для вызова Python из потока C теперь таков:

PyGILState_STATE gstate;
gstate = PyGILState_Ensure();

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

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

Обратите внимание, что функции PyGILState_*() предполагают наличие только одного глобального интерпретатора (созданного автоматически вызовом Py_Initialize()). Python по-прежнему поддерживает создание дополнительных интерпретаторов (с помощью Py_NewInterpreter()), но смешивание нескольких интерпретаторов и API PyGILState_*() не поддерживается.

Ещё один важный момент, касающийся потоков – это их поведение при вызове C-функции fork(). На большинстве систем с fork() после разветвления (fork) процесса существовать будет только тот поток, который вызвал fork. Это также означает, что любые блокировки, удерживаемые другими потоками, никогда не будут освобождены. Python решает эту проблему для os.fork(), захватывая используемые им внутренние блокировки перед fork и освобождая их после. Кроме того, он сбрасывает любые объекты блокировок в дочернем процессе. При расширении или встраивании Python нет способа сообщить Python о дополнительных (не-Python) блокировках, которые необходимо захватить перед fork или сбросить после. Для достижения того же эффекта потребуется использовать системные средства, такие как posix_atfork(). Кроме того, при расширении или встраивании Python прямой вызов fork() вместо вызова через os.fork() (и возврат в Python или вызов кода Python) может привести к взаимоблокировке из-за того, что одна из внутренних блокировок Python остаётся удерживаемой потоком, который после fork перестаёт существовать. PyOS_AfterFork() пытается сбросить необходимые блокировки, но это удаётся не всегда.

PyInterpreterState¶

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

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

PyThreadState¶

Эта структура данных представляет состояние одного потока. Единственная открытая (public) переменная-член – PyInterpreterState *interp, которая указывает на состояние интерпретатора этого потока.

void PyEval_InitThreads()¶

Инициализирует и захватывает глобальную блокировку интерпретатора. Она должна вызываться в главном потоке перед созданием второго потока или выполнением любых других операций с потоками, таких как PyEval_ReleaseLock() или PyEval_ReleaseThread(tstate). Её не нужно вызывать перед PyEval_SaveThread() или PyEval_RestoreThread().

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

Когда существует только главный поток, операции с GIL не нужны. Это обычная ситуация (большинство программ на Python не использует потоки), и операции блокировки немного замедляют интерпретатор. Поэтому блокировка изначально не создаётся. Эта ситуация эквивалентна захвату блокировки: при наличии единственного потока все обращения к объектам безопасны. Поэтому, когда эта функция инициализирует глобальную блокировку интерпретатора, она также её захватывает. Прежде чем модуль Python thread создаст новый поток, он, зная, что либо блокировка у него уже есть, либо она ещё не создана, вызывает PyEval_InitThreads(). Когда этот вызов завершается, гарантируется, что блокировка создана и вызывающий поток её захватил.

Небезопасно вызывать эту функцию, когда неизвестно, какой поток (если таковой есть) в данный момент удерживает глобальную блокировку интерпретатора.

Эта функция недоступна, если поддержка потоков отключена на этапе компиляции.

int PyEval_ThreadsInitialized()¶

Возвращает ненулевое значение, если PyEval_InitThreads() была вызвана. Эту функцию можно вызывать без захвата GIL, и поэтому её можно использовать, чтобы избежать вызовов API блокировки при однопоточной работе. Функция недоступна, если поддержка потоков отключена во время компиляции.

Новое в версии 2.4.

void PyEval_AcquireLock()¶

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

void PyEval_ReleaseLock()¶

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

void PyEval_AcquireThread(PyThreadState *tstate)¶

Захватывает глобальную блокировку интерпретатора и устанавливает текущее состояние потока в tstate, которое не должно быть NULL. Блокировка должна быть создана ранее. Если этот поток уже владеет блокировкой, возникнет взаимная блокировка. Эта функция недоступна, если поддержка потоков отключена при компиляции.

void PyEval_ReleaseThread(PyThreadState *tstate)¶

Сбрасывает текущее состояние потока в NULL и освобождает глобальную блокировку интерпретатора. Блокировка должна быть создана ранее и должна удерживаться текущим потоком. Аргумент tstate, который не должен быть NULL, используется только для проверки, что он представляет текущее состояние потока – если нет, сообщается о фатальной ошибке. Эта функция недоступна, если поддержка потоков отключена при компиляции.

PyThreadState* PyEval_SaveThread()¶

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

void PyEval_RestoreThread(PyThreadState *tstate)¶

Захватывает глобальную блокировку интерпретатора (если она создана и поддержка потоков включена) и устанавливает состояние потока в tstate, который не должен быть NULL. Если блокировка была создана, текущий поток не должен был захватить её, иначе возникнет взаимоблокировка. (Эта функция доступна, даже если поддержка потоков отключена на этапе компиляции.)

void PyEval_ReInitThreads()¶

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

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

Py_BEGIN_ALLOW_THREADS¶

Этот макрос раскрывается в { PyThreadState *_save; _save = PyEval_SaveThread();. Обратите внимание, что он содержит открывающую фигурную скобку; он должен быть уравновешен последующим макросом Py_END_ALLOW_THREADS. См. выше обсуждение этого макроса. Ничего не делает, если поддержка потоков отключена во время компиляции.

Py_END_ALLOW_THREADS¶

Этот макрос раскрывается в PyEval_RestoreThread(_save); }. Обратите внимание, что он содержит закрывающую фигурную скобку; он должен быть уравновешен предшествующим макросом Py_BEGIN_ALLOW_THREADS. См. выше обсуждение этого макроса. Ничего не делает, если поддержка потоков отключена во время компиляции.

Py_BLOCK_THREADS¶

Этот макрос раскрывается в PyEval_RestoreThread(_save);: он эквивалентен Py_END_ALLOW_THREADS без закрывающей фигурной скобки. Он не выполняет никаких действий, если поддержка потоков отключена на этапе компиляции.

Py_UNBLOCK_THREADS¶

Этот макрос раскрывается в _save = PyEval_SaveThread();: он эквивалентен Py_BEGIN_ALLOW_THREADS без открывающей фигурной скобки и объявления переменной. Он не выполняет никаких действий, если поддержка потоков отключена на этапе компиляции.

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

PyInterpreterState* PyInterpreterState_New()¶

Создаёт новый объект состояния интерпретатора. Глобальная блокировка интерпретатора может не удерживаться, но может удерживаться, если необходимо сериализовать вызовы этой функции.

void PyInterpreterState_Clear(PyInterpreterState *interp)¶

Сбрасывает всю информацию в объекте состояния интерпретатора. Глобальная блокировка интерпретатора должна удерживаться.

void PyInterpreterState_Delete(PyInterpreterState *interp)¶

Уничтожает объект состояния интерпретатора. Глобальная блокировка интерпретатора может не удерживаться. Состояние интерпретатора должно быть сброшено предварительным вызовом PyInterpreterState_Clear().

PyThreadState* PyThreadState_New(PyInterpreterState *interp)¶

Создаёт новый объект состояния потока, принадлежащий данному объекту интерпретатора. Глобальная блокировка интерпретатора может не удерживаться, но может удерживаться, если необходимо сериализовать вызовы этой функции.

void PyThreadState_Clear(PyThreadState *tstate)¶

Сбрасывает всю информацию в объекте состояния потока. Глобальная блокировка интерпретатора должна удерживаться.

void PyThreadState_Delete(PyThreadState *tstate)¶

Уничтожает объект состояния потока. Глобальная блокировка интерпретатора может не удерживаться. Состояние потока должно быть сброшено предварительным вызовом PyThreadState_Clear().

PyThreadState* PyThreadState_Get()¶

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

PyThreadState* PyThreadState_Swap(PyThreadState *tstate)¶

Заменяет текущее состояние потока на состояние потока, заданное аргументом tstate, который может быть NULL. Глобальная блокировка интерпретатора должна быть удержана.

PyObject* PyThreadState_GetDict()¶

Возвращаемое значение: заимствованная ссылка.

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

Изменено в версии 2.3: Ранее это можно было вызывать только при активном текущем потоке, и NULL означал, что было возбуждено исключение.

int PyThreadState_SetAsyncExc(long id, PyObject *exc)¶

Асинхронно возбуждает исключение в потоке. Аргумент id – это идентификатор потока целевого потока; exc – объект исключения, которое нужно возбудить. Эта функция не похищает никаких ссылок на exc. Чтобы предотвратить наивное злоупотребление, вы должны написать собственное расширение C для её вызова. Должна вызываться с захваченным GIL. Возвращает количество изменённых состояний потока; обычно это единица, но будет нулём, если идентификатор потока не найден. Если exc равно NULL, то ожидающее исключение (если есть) для потока очищается. Эта функция не возбуждает исключений.

Новое в версии 2.3.

PyGILState_STATE PyGILState_Ensure()¶

Гарантирует, что текущий поток готов вызывать Python C API независимо от текущего состояния Python или глобальной блокировки интерпретатора. Может вызываться потоком сколько угодно раз, при условии, что каждый вызов соответствует вызову PyGILState_Release(). В общем случае между вызовами PyGILState_Ensure() и PyGILState_Release() можно использовать другие API, связанные с потоками, при условии, что состояние потока будет восстановлено до предыдущего перед вызовом Release(). Например, допустимо обычное использование макросов Py_BEGIN_ALLOW_THREADS и Py_END_ALLOW_THREADS.

Возвращаемое значение – непрозрачный «дескриптор» состояния потока на момент вызова PyGILState_Ensure(), и его необходимо передать в PyGILState_Release(), чтобы гарантировать, что Python останется в том же состоянии. Хотя рекурсивные вызовы разрешены, эти дескрипторы нельзя разделять – каждый уникальный вызов PyGILState_Ensure() должен сохранить дескриптор для своего вызова PyGILState_Release().

При возврате из функции текущий поток будет удерживать GIL. Сбой является фатальной ошибкой.

Новое в версии 2.3.

void PyGILState_Release(PyGILState_STATE)¶

Освобождает все ранее захваченные ресурсы. После этого вызова состояние Python будет таким же, как до соответствующего вызова PyGILState_Ensure() (но обычно это состояние неизвестно вызывающей стороне, отсюда и использование GILState API.)

Каждый вызов PyGILState_Ensure() должен быть уравновешен вызовом PyGILState_Release() в том же потоке.

Новое в версии 2.3.

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

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

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

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

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

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

int PyTrace_CALL¶

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

int PyTrace_EXCEPTION¶

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

int PyTrace_LINE¶

Значение, передаваемое в качестве параметра what в трассировочную функцию (но не в профилирующую функцию), когда сообщается о событии номера строки.

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 вернулась.

void PyEval_SetProfile(Py_tracefunc func, PyObject *obj)¶

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

void PyEval_SetTrace(Py_tracefunc func, PyObject *obj)¶

Устанавливает функцию трассировки в func. Это похоже на PyEval_SetProfile(), за исключением того, что функция трассировки получает события номеров строк.

PyObject* PyEval_GetCallStats(PyObject *self)¶

Возвращает кортеж счётчиков вызовов функций. Для позиций в кортеже определены константы:

Имя	Значение
PCALL_ALL	0
PCALL_FUNCTION	1
PCALL_FAST_FUNCTION	2
PCALL_FASTER_FUNCTION	3
PCALL_METHOD	4
PCALL_BOUND_METHOD	5
PCALL_CFUNCTION	6
PCALL_TYPE	7
PCALL_GENERATOR	8
PCALL_OTHER	9
PCALL_POP	10

PCALL_FAST_FUNCTION означает, что создавать кортеж аргументов не требуется. PCALL_FASTER_FUNCTION означает, что используется код быстрой настройки фрейма.

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

Эта функция доступна только при компиляции Python с определённым CALL_PROFILE.

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

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

PyInterpreterState* PyInterpreterState_Head()¶

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

Новое в версии 2.2.

PyInterpreterState* PyInterpreterState_Next(PyInterpreterState *interp)¶

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

Новое в версии 2.2.

PyThreadState * PyInterpreterState_ThreadHead(PyInterpreterState *interp)¶

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

Новое в версии 2.2.

PyThreadState* PyThreadState_Next(PyThreadState *tstate)¶

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

Новое в версии 2.2.