_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 аргумента обработчика содержит 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()

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

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

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

_thread.stack_size([size])

Возвращает размер стека потока, используемый при создании новых потоков. Необязательный аргумент size задаёт размер стека для создаваемых впоследствии потоков и должен быть равен 0 (использовать значение по умолчанию для платформы или конфигурации) либо положительным целым числом не меньше 32 768 (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, действие зависит от его значения: если он равен false, блокировка захватывается только в том случае, если это можно сделать немедленно, без ожидания; если он равен true, блокировка захватывается безусловно, как описано выше.

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

Возвращаемое значение — 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).
• Вызов sys.exit() или возбуждение исключения SystemExit равносильны вызову _thread.exit().
• Возможность прерывания метода acquire() для блокировки зависит от платформы (то есть исключение KeyboardInterrupt может быть вызвано немедленно, а не только после захвата блокировки или истечения времени ожидания). В POSIX прерывание возможно, а в Windows — нет.
• При завершении главного потока судьба остальных потоков определяется системой. В большинстве систем их принудительно завершают без выполнения блоков try … finally или деструкторов объектов.