_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 оно игнорируется.

Изменено в версии 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()

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

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

Введено в версии 3.8.

_thread.stack_size([size])

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

Доступность: Windows, системы с POSIX-потоками.

_thread.TIMEOUT_MAX

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

Введено в версии 3.2.

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

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

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

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

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

Возвращаемое значение — 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 выполняются), и стандартные файлы ввода-вывода не очищаются.