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

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

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

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

Интерпретатору Python необходимо хранить некоторую служебную информацию отдельно для каждого потока – для этого используется структура данных, называемая PyThreadState. Однако существует одна глобальная переменная: указатель на текущую структуру PyThreadState. Хотя большинство пакетов для работы с потоками имеют способ хранения «глобальных данных потока», внутренняя платформенно-независимая абстракция потоков Python пока этого не поддерживает. Поэтому с текущим состоянием потока необходимо работать явно.

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

Save the thread state in a local variable.
Release the interpreter lock.
...Do some blocking I/O operation...
Reacquire the 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 скомпилирован без поддержки потоков, они определяются пустыми, что экономит операции с состоянием потока и блокировкой.

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

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 не работают с блокировкой; в этом случае PyEval_ReleaseLock и PyEval_AcquireLock недоступны. Это сделано для того, чтобы динамически загружаемые расширения, скомпилированные с поддержкой потоков, могли быть загружены интерпретатором, скомпилированным без поддержки потоков.

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

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

Потоки могут воспользоваться функциями 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_* не поддерживается.

PyInterpreterState¶

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

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

PyThreadState¶

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

void PyEval_InitThreads()¶

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

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

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

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

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

int PyEval_ThreadsInitialized()¶

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

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

int PyThreadState_SetAsyncExc(long id, PyObject *exc)¶

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

PyGILState_STATE PyGILState_Ensure()¶

Гарантирует, что текущий поток готов вызывать C API Python независимо от текущего состояния 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. Сбой является фатальной ошибкой.

void PyGILState_Release(PyGILState_STATE)¶

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

Каждый вызов PyGILState_Ensure должен сопровождаться вызовом PyGILState_Release в том же потоке.

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

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

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

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

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

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

PyInterpreterState* PyInterpreterState_Next(PyInterpreterState *interp)¶

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

PyThreadState * PyInterpreterState_ThreadHead(PyInterpreterState *interp)¶

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

PyThreadState* PyThreadState_Next(PyThreadState *tstate)¶

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