_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, 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. Если указать значение тайм-аута, превышающее это значение, возникнет исключение OverflowError.

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

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

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

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

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

Если задан положительный аргумент 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 и деструкторов объектов.