_thread — API многопоточности низкого уровня

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

В этом модуле определены следующие константы и функции:

exception _thread.error

Вызывается при ошибках, специфичных для потоков.

Изменено в версии 3.3: Теперь это синоним встроенной ошибки RuntimeError.

_thread.LockType

Это тип объектов блокировки.

_thread.start_new_thread(function, args[, kwargs])

Запустить новый поток и вернуть его идентификатор. Поток выполняет функцию function со списком аргументов args (который должен быть кортежем). Необязательный аргумент kwargs задаёт словарь аргументов ключевых слов.

Когда функция возвращает значение, поток бесшумно завершается.

Когда функция завершается с необработанным исключением, вызывается sys.unraisablehook() для обработки исключения. Атрибут object аргумента hook равен function. По умолчанию выводится трассировка стека, а затем поток завершается (но другие потоки продолжают работать).

Когда функция вызывает исключение SystemExit, оно бесшумно игнорируется.

Вызывает событие аудита _thread.start_new_thread с аргументами function, args, kwargs.

Изменено в версии 3.8: sys.unraisablehook() теперь используется для обработки необработанных исключений.

_thread.interrupt_main(signum=signal.SIGINT, /)

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

Если задано, signum — это номер сигнала для имитации. Если signum не задан, имитируется signal.SIGINT.

Если заданный сигнал не обрабатывается Python (он был установлен в signal.SIG_DFL или signal.SIG_IGN), эта функция ничего не делает.

Изменено в версии 3.10: Добавлен аргумент signum для настройки номера сигнала.

Примечание

Это не генерирует соответствующий сигнал, а планирует вызов связанного обработчика (если он существует). Если вы хотите действительно сгенерировать сигнал, используйте signal.raise_signal().

_thread.exit()

Вызывает исключение SystemExit. При отсутствии перехвата это приведёт к бесшумному завершению потока.

_thread.allocate_lock()

Возвращает новый объект блокировки. Методы блокировок описаны ниже. Блокировка изначально разблокирована.

_thread.get_ident()

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

_thread.get_native_id()

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

Доступность: Windows, FreeBSD, Linux, macOS, OpenBSD, NetBSD, AIX, DragonFlyBSD.

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

_thread.stack_size([size])

Возвращает размер стека потока, используемый при создании новых потоков. Необязательный аргумент size задаёт размер стека для последующих созданных потоков и должен быть 0 (используется платформа или конфигурированное значение по умолчанию) или положительным целым числом, не меньшим 32768 (32 КБ). Если size не указан, используется 0. Если изменение размера стека потока не поддерживается, генерируется RuntimeError. Если указанный размер стека некорректен, генерируется ValueError, и размер стека не изменяется. 32 КБ в настоящее время является минимально поддерживаемым размером стека для обеспечения достаточного пространства стека для самого интерпретатора. Обратите внимание, что некоторые платформы могут иметь особые ограничения на значения размера стека, такие как требование минимального размера стека > 32 КБ или требование выделения кратно размеру страницы системной памяти — для получения дополнительной информации следует обратиться к документации платформы (4 КБ страницы распространены; использование кратных значений 4096 для размера стека рекомендуется в отсутствие более конкретной информации).

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

Платформы Unix с поддержкой POSIX-потоков.

_thread.TIMEOUT_MAX

Максимальное значение, разрешённое для параметра timeout в Lock.acquire. Указание значения таймаута, большего этого значения, вызовет OverflowError.

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

Объекты блокировки имеют следующие методы:

lock.acquire(blocking=True, timeout=-1)

Без каких-либо необязательных аргументов этот метод приобретает блокировку безусловно, при необходимости ожидая, пока она не будет освобождена другим потоком (только один поток за раз может приобрести блокировку — именно поэтому они существуют).

Если аргумент blocking присутствует, действие зависит от его значения: если он ложный, блокировка приобретается только в том случае, если её можно приобрести немедленно без ожидания, в то время как если он истинный, блокировка приобретается безусловно, как указано выше.

Если присутствует плавающее значение аргумента timeout и оно положительно, оно задаёт максимальное время ожидания в секундах, прежде чем вернуть значение. Отрицательное значение timeout указывает неограниченное ожидание. Вы не можете указать timeout, если blocking ложный.

Возвращаемое значение — True если блокировка приобретена успешно, False если нет.

Изменено в версии 3.2: Параметр timeout является новым.

Изменено в версии 3.2: Приобретение блокировки на платформах POSIX теперь может прерываться сигналами.

lock.release()

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

lock.locked()

Возвращает состояние блокировки: True если она была приобретена каким-либо потоком, False если нет.

В дополнение к этим методам объекты блокировки также могут быть использованы с помощью оператора with, например:

import _thread

a_lock = _thread.allocate_lock()

with a_lock:
    print("a_lock is locked while this executes")

Ограничения:

• Потоки взаимодействуют со прерываниями необычным образом: исключение KeyboardInterrupt будет получено произвольным потоком. (Когда модуль signal доступен, прерывания всегда поступают в основной поток.)
• Вызов sys.exit() или поднятие исключения SystemExit эквивалентно вызову _thread.exit().
• Невозможно прервать метод acquire() на блокировке — исключение KeyboardInterrupt произойдёт после того, как блокировка будет получена.
• Когда основной поток завершается, определяется системой, выживают ли другие потоки. На большинстве систем они уничтожаются без выполнения блоков try … finally или выполнения деструкторов объектов.
• Когда основной поток завершается, он не выполняет никакой обычной очистки (кроме случаев, когда выполняются блоки try … finally), а стандартные файлы ввода-вывода не сбрасываются.