This document is for an old version of Python that is no longer supported. You should upgrade, and read the Python documentation for the current stable release.

# `_thread` — Low-level threading API

Цей модуль надає низькорівневі примітиви для роботи з кількома потоками (також званими light-weight processes або tasks) — кілька потоків управління спільно використовують свій глобальний простір даних. Для синхронізації передбачені прості блокування (також звані mutexes або binary semaphores). Модуль `threading` надає більш простий у використанні та високорівневий потоковий API, побудований на основі цього модуля.

Змінено в версії 3.7: Раніше цей модуль був необов’язковим, тепер він доступний завжди.

Цей модуль визначає такі константи та функції:

exception `_thread.``error`

  Виникає через помилки потоку.

  Змінено в версії 3.3: Тепер це синонім вбудованої `RuntimeError`.

`_thread.``LockType`

  Це тип об’єктів блокування.

`_thread.``start_new_thread`(function, args[, kwargs])

  Створіть новий потік і поверніть його ідентифікатор. Потік виконує функцію function зі списком аргументів args (який має бути кортежем). Необов’язковий аргумент kwargs визначає словник ключових аргументів.

  Коли функція повертається, потік мовчки виходить.

  Коли функція завершується з необробленим винятком, `sys.unraisablehook()` викликається для обробки винятку. Атрибутом object аргументу hook є function. За замовчуванням трасування стека друкується, а потім потік завершується (але інші потоки продовжують працювати).

  Коли функція викликає виняткову ситуацію `SystemExit`, вона мовчки ігнорується.

  Змінено в версії 3.8: `sys.unraisablehook()` тепер використовується для обробки необроблених винятків.

`_thread.``interrupt_main`()

  Simulate the effect of a `signal.SIGINT` signal arriving in the main thread. A thread can use this function to interrupt the main thread.

  If `signal.SIGINT` isn’t handled by Python (it was set to `signal.SIG_DFL` or `signal.SIG_IGN`), this function does nothing.

`_thread.``exit`()

  Підніміть виняток `SystemExit`. Якщо не буде спіймано, це призведе до тихого виходу потоку.

`_thread.``allocate_lock`()

  Повернути новий об’єкт блокування. Способи блокування описані нижче. Замок спочатку розблокований.

`_thread.``get_ident`()

  Повертає «ідентифікатор потоку» поточного потоку. Це ненульове ціле число. Його значення не має прямого значення; воно призначене як магічне печиво, яке можна використовувати, наприклад. щоб індексувати словник даних, що стосуються потоку. Ідентифікатори потоку можуть бути перероблені, коли потік завершується та створюється інший.

`_thread.``get_native_id`()

  Повертає власний інтегральний ідентифікатор потоку поточного потоку, призначеного ядром. Це невід’ємне ціле число. Його значення може використовуватися для однозначної ідентифікації цього конкретного потоку в системі (до завершення роботи потоку, після чого значення може бути повторно використано ОС).

  Availability: 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 для розміру стека є запропонованим підходом за відсутності більш конкретної інформації).

  Availability: Windows, systems with POSIX threads.

`_thread.``TIMEOUT_MAX`

  The maximum value allowed for the timeout parameter of `Lock.acquire()`. Specifying a timeout greater than this value will raise an `OverflowError`.

  Нове в версії 3.2.

Об’єкти блокування мають такі методи:

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

  Без будь-яких необов’язкових аргументів цей метод отримує блокування безумовно, за необхідності чекаючи, поки його не буде звільнено іншим потоком (лише один потік за раз може отримати блокування — це причина їхнього існування).

  If the integer waitflag argument is present, the action depends on its value: if it is zero, the lock is only acquired if it can be acquired immediately without waiting, while if it is nonzero, the lock is acquired unconditionally as above.

  If the floating-point timeout argument is present and positive, it specifies the maximum wait time in seconds before returning. A negative timeout argument specifies an unbounded wait. You cannot specify a timeout if waitflag is zero.

  Поверненим значенням є `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")

Застереження:

- Threads interact strangely with interrupts: the `KeyboardInterrupt` exception will be received by an arbitrary thread. (When the `signal` module is available, interrupts always go to the main thread.)

- Виклик `sys.exit()` або підвищення винятку `SystemExit` еквівалентний виклику `_thread.exit()`.

- It is not possible to interrupt the `acquire()` method on a lock — the `KeyboardInterrupt` exception will happen after the lock has been acquired.

- Коли основний потік виходить, система визначає, чи виживуть інші потоки. У більшості систем вони припиняються без виконання пропозицій `try` … `finally` або виконання деструкторів об’єктів.

- When the main thread exits, it does not do any of its usual cleanup (except that `try` … `finally` clauses are honored), and the standard I/O files are not flushed.