_thread — низкоуровневый API для работы с потоками

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

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

exception _thread.error

Возникает при ошибках, связанных с потоками.

Изменено в версии 3.3: Теперь это псевдоним встроенного исключения RuntimeError.

_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, GNU/kFreeBSD.

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

Изменено в версии 3.13: Добавлена поддержка GNU/kFreeBSD.

_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. Если указать значение timeout больше этого значения, возникнет исключение OverflowError.

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

class _thread.LockType

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

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

acquire(blocking=True, timeout=-1)

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

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

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

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

Изменено в версии 3.2: Добавлен параметр timeout.

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

Изменено в версии 3.14: Теперь захват блокировки может прерываться сигналами в Windows.

release()

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

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().
• При завершении главного потока поведение остальных потоков определяется системой. В большинстве систем они завершаются, не выполняя блоки try … finally и деструкторы объектов.