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

Вызывает событие аудита auditing event _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 (использовать платформенное или конфигурируемое значение по умолчанию), либо положительным целым числом не менее 32768 (32 Кб). Если size не указан, используется 0. Если изменение размера стека потока не поддерживается, возникает RuntimeError. Если заданный размер стека некорректен, возникает ValueError, и размер стека не меняется. 32 Кб — это минимальный поддерживаемый размер стека для обеспечения достаточного пространства стека для самого интерпретатора. Обратите внимание, что на некоторых платформах могут быть определённые ограничения на значения размера стека, например, минимальный размер стека > 32 Кб или требование выделения кратно размеру страницы памяти системы — для получения дополнительной информации следует обратиться к документации платформы (размер страницы 4 Кб является распространённым; использование кратных значений 4096 для размера стека рекомендуется при отсутствии более конкретной информации).

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

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

_thread.TIMEOUT_MAX

Максимальное значение, разрешённое для параметра timeout метода Lock.acquire. Указание значения timeout, большего этого значения, приведёт к возбуждению исключения 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 будет получено этим потоком.)
• Вызов sys.exit() или возбуждение исключения SystemExit эквивалентно вызову _thread.exit().
• Зависит от платформы, может ли метод acquire() блокировки быть прерван (так что исключение KeyboardInterrupt произойдет немедленно, а не только после того, как блокировка была получена или операция истекла). На POSIX это возможно, но не на Windows.
• Когда основной поток завершается, определено системой, выживут ли другие потоки. На большинстве систем они убиваются без выполнения блоков try … finally или выполнения деструкторов объектов.