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

Изменено в версии 3.8: Для обработки необработанных исключений теперь используется sys.unraisablehook().

_thread.interrupt_main()

Имитирует эффект сигнала signal.SIGINT, поступающего в основной поток. Поток может использовать эту функцию для прерывания основного потока.

Если сигнал signal.SIGINT не обрабатывается Python (он был установлен в значение signal.SIG_DFL или signal.SIG_IGN), эта функция ничего не делает.

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

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

_thread.TIMEOUT_MAX

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

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

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

lock.acquire(waitflag=1, timeout=-1)

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

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

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

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