`threading.md`

597 строк · 74.7 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.2/library/threading.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# 16.2. [`threading`](https://python-all.ru/3.2/library/threading.html#module-threading) – Параллелизм на основе потоков89**Исходный код:** [Lib/threading.py](https://python-all.ru/src/3.2/Lib/threading.py)1011---1213Этот модуль предоставляет интерфейсы threading более высокого уровня поверх низкоуровневого модуля [`_thread`](https://python-all.ru/3.2/library/_thread.html#module-_thread). Смотрите также модуль [`queue`](https://python-all.ru/3.2/library/queue.html#module-queue).1415Модуль [`dummy_threading`](https://python-all.ru/3.2/library/dummy_threading.html#module-dummy_threading) предназначен для ситуаций, когда [`threading`](https://python-all.ru/3.2/library/threading.html#module-threading) не может использоваться, поскольку [`_thread`](https://python-all.ru/3.2/library/_thread.html#module-_thread) отсутствует.1617> **Примечание**18>19> Хотя они не перечислены ниже, имена в стиле `camelCase`, использовавшиеся для некоторых методов и функций в этом модуле в серии Python 2.x, по-прежнему поддерживаются этим модулем.2021**Деталь реализации CPython:** В CPython из-за [*глобальная блокировка интерпретатора (Global Interpreter Lock)*](https://python-all.ru/3.2/glossary.html#term-global-interpreter-lock) одновременно может выполняться только один поток Python (хотя некоторые библиотеки, ориентированные на производительность, могут обойти это ограничение). Если вы хотите, чтобы ваше приложение лучше использовало вычислительные ресурсы многоядерных машин, рекомендуется использовать [`multiprocessing`](https://python-all.ru/3.2/library/multiprocessing.html#module-multiprocessing) или [`concurrent.futures.ProcessPoolExecutor`](https://python-all.ru/3.2/library/concurrent.futures.html#concurrent.futures.ProcessPoolExecutor). Однако threading по-прежнему является подходящей моделью, если требуется одновременное выполнение нескольких задач, связанных с вводом-выводом.2223Этот модуль определяет следующие функции и объекты:2425#### `threading.active_count()`2627Возвращает количество объектов [`Thread`](https://python-all.ru/3.2/library/threading.html#threading.Thread), которые в данный момент активны. Возвращаемое количество равно длине списка, возвращаемого [`enumerate()`](https://python-all.ru/3.2/library/threading.html#threading.enumerate).2829#### `threading.Condition()`3031Фабричная функция, возвращающая новый объект условной переменной. Условная переменная позволяет одному или нескольким потокам ожидать, пока другой поток не уведомит их.3233См. [*Объекты Condition*](https://python-all.ru/3.2/library/threading.html#condition-objects).3435#### `threading.current_thread()`3637Возвращает текущий объект [`Thread`](https://python-all.ru/3.2/library/threading.html#threading.Thread), соответствующий потоку управления вызывающего кода. Если поток управления вызывающего кода не был создан через модуль [`threading`](https://python-all.ru/3.2/library/threading.html#module-threading), возвращается фиктивный объект потока с ограниченной функциональностью.3839#### `threading.enumerate()`4041Возвращает список всех объектов [`Thread`](https://python-all.ru/3.2/library/threading.html#threading.Thread), которые в данный момент активны. Список включает потоки-демоны, фиктивные объекты потоков, созданные [`current_thread()`](https://python-all.ru/3.2/library/threading.html#threading.current_thread), и главный поток. Он исключает завершённые потоки и потоки, которые ещё не были запущены.4243#### `threading.Event()`4445Фабричная функция, возвращающая новый объект события. Событие управляет флагом, который можно установить в true с помощью метода [`set()`](https://python-all.ru/3.2/library/threading.html#threading.Event.set) и сбросить в false с помощью метода `clear()`. Метод `wait()` блокируется, пока флаг не станет true.4647См. [*Объекты Event*](https://python-all.ru/3.2/library/threading.html#event-objects).4849#### `class threading.local`5051Класс, представляющий локальные данные потока. Локальные данные потока – это данные, значения которых специфичны для потока. Чтобы управлять локальными данными потока, достаточно создать экземпляр [`local`](https://python-all.ru/3.2/library/threading.html#threading.local) (или подкласс) и сохранять атрибуты в нем:5253```python54mydata = threading.local()55mydata.x = 156```5758Значения экземпляра будут разными для разных потоков.5960Для получения более подробной информации и многочисленных примеров обратитесь к строке документации модуля `_threading_local`.6162#### `threading.Lock()`6364Фабричная функция, возвращающая новый объект примитивной блокировки. Как только поток захватил блокировку, последующие попытки захватить её блокируются, пока она не будет освобождена; любой поток может освободить её.6566См. [*Объекты блокировки*](https://python-all.ru/3.2/library/threading.html#lock-objects).6768#### `threading.RLock()`6970Фабричная функция, возвращающая новый объект реентерабельной блокировки. Реентерабельная блокировка должна быть освобождена тем потоком, который её захватил. После того как поток захватил реентерабельную блокировку, тот же поток может захватить её снова без блокировки; поток должен освободить её по одному разу за каждое захватывание.7172См. [*Объекты RLock*](https://python-all.ru/3.2/library/threading.html#rlock-objects).7374#### `threading.Semaphore(value=1)`7576Фабричная функция, возвращающая новый объект семафора. Семафор управляет счётчиком, представляющим количество вызовов `release()` минус количество вызовов `acquire()` плюс начальное значение. Метод `acquire()` блокируется при необходимости, пока не сможет вернуться, не сделав счётчик отрицательным. Если не указан, *value* по умолчанию равен 1.7778См. [*Объекты Semaphore*](https://python-all.ru/3.2/library/threading.html#semaphore-objects).7980#### `threading.BoundedSemaphore(value=1)`8182Фабричная функция, возвращающая новый объект ограниченного семафора. Ограниченный семафор проверяет, что его текущее значение не превышает начальное. Если это происходит, возбуждается [`ValueError`](https://python-all.ru/3.2/library/exceptions.html#ValueError). В большинстве случаев семафоры используются для защиты ресурсов с ограниченной ёмкостью. Если семафор освобождается слишком много раз, это признак ошибки. Если не указан, *value* по умолчанию равен 1.8384#### `class threading.Thread`8586Класс, представляющий поток управления. Этот класс можно безопасно наследовать ограниченным образом.8788См. [*Объекты потока*](https://python-all.ru/3.2/library/threading.html#thread-objects).8990#### `class threading.Timer`9192Поток, выполняющий функцию по истечении заданного интервала времени.9394См. [*Объекты Timer*](https://python-all.ru/3.2/library/threading.html#timer-objects).9596#### `threading.settrace(func)`9798Устанавливает трассировочную функцию для всех потоков, запущенных из модуля [`threading`](https://python-all.ru/3.2/library/threading.html#module-threading). Функция *func* будет передана в [`sys.settrace()`](https://python-all.ru/3.2/library/sys.html#sys.settrace) для каждого потока перед вызовом его метода `run()`.99100#### `threading.setprofile(func)`101102Устанавливает профилирующую функцию для всех потоков, запущенных из модуля [`threading`](https://python-all.ru/3.2/library/threading.html#module-threading). Функция *func* будет передана в [`sys.setprofile()`](https://python-all.ru/3.2/library/sys.html#sys.setprofile) для каждого потока перед вызовом его метода `run()`.103104#### `threading.stack_size([size])`105106Возвращает размер стека потока, используемый при создании новых потоков. Необязательный *size* аргумент задаёт размер стека для последующих создаваемых потоков и должен быть равен 0 (используется платформенное или сконфигурированное значение по умолчанию) или положительному целому числу не менее 32 768 (32 кБ). Если изменение размера стека потока не поддерживается, возбуждается `ThreadError`. Если указанный размер стека некорректен, возбуждается [`ValueError`](https://python-all.ru/3.2/library/exceptions.html#ValueError), а размер стека не изменяется. 32 кБ – это минимальный поддерживаемый размер стека, гарантирующий достаточное пространство для самого интерпретатора. Обратите внимание, что некоторые платформы могут накладывать особые ограничения на значения размера стека, например, требовать минимальный размер \> 32 кБ или выделение памяти, кратное размеру страницы системной памяти – для получения дополнительных сведений следует обращаться к документации платформы (страницы по 4 кБ распространены; при отсутствии более точной информации рекомендуется использовать размер стека, кратный 4096). Доступность: Windows, системы с потоками POSIX.107108Этот модуль также определяет следующую константу:109110#### `threading.TIMEOUT_MAX`111112Максимально допустимое значение для параметра *timeout* блокирующих функций ([`Lock.acquire()`](https://python-all.ru/3.2/library/threading.html#threading.Lock.acquire), [`RLock.acquire()`](https://python-all.ru/3.2/library/threading.html#threading.RLock.acquire), [`Condition.wait()`](https://python-all.ru/3.2/library/threading.html#threading.Condition.wait) и т.д.). Указание тайм-аута, превышающего это значение, вызовет исключение [`OverflowError`](https://python-all.ru/3.2/library/exceptions.html#OverflowError).113114Новое в версии 3.2.115116Подробные интерфейсы объектов описаны ниже.117118Дизайн этого модуля основан на модели потоков Java, хотя и не строго. Однако, если в Java блокировки и переменные условий являются базовым поведением каждого объекта, в Python они являются отдельными объектами. Класс [`Thread`](https://python-all.ru/3.2/library/threading.html#threading.Thread) в Python поддерживает подмножество поведения класса Thread в Java; в настоящее время нет приоритетов, групп потоков, и потоки не могут быть уничтожены, остановлены, приостановлены, возобновлены или прерваны. Статические методы класса Thread в Java при их реализации отображаются на функции уровня модуля.119120Все описанные ниже методы выполняются атомарно.121122## 16.2.1. Объекты потока123124Этот класс представляет собой активность, выполняемую в отдельном потоке управления. Есть два способа определить активность: передать вызываемый объект в конструктор или переопределить метод [`run()`](https://python-all.ru/3.2/library/threading.html#threading.Thread.run) в подклассе. Никакие другие методы (кроме конструктора) не следует переопределять в подклассе. Иными словами, *только* переопределяйте методы `__init__()` и [`run()`](https://python-all.ru/3.2/library/threading.html#threading.Thread.run) этого класса.125126После создания объекта потока его действие необходимо запустить вызовом метода [`start()`](https://python-all.ru/3.2/library/threading.html#threading.Thread.start) этого потока. Это вызовет метод [`run()`](https://python-all.ru/3.2/library/threading.html#threading.Thread.run) в отдельном потоке управления.127128Когда действие потока запущено, поток считается «живым». Он перестаёт быть живым, когда его метод [`run()`](https://python-all.ru/3.2/library/threading.html#threading.Thread.run) завершается – либо нормально, либо из-за необработанного исключения. Метод [`is_alive()`](https://python-all.ru/3.2/library/threading.html#threading.Thread.is_alive) проверяет, жив ли поток.129130Другие потоки могут вызывать метод [`join()`](https://python-all.ru/3.2/library/threading.html#threading.Thread.join) потока. Это блокирует вызывающий поток до тех пор, пока поток, чей метод [`join()`](https://python-all.ru/3.2/library/threading.html#threading.Thread.join) был вызван, не завершится.131132У потока есть имя. Имя можно передать конструктору, а также прочитать или изменить через атрибут [`name`](https://python-all.ru/3.2/library/threading.html#threading.Thread.name).133134Поток можно пометить как «фоновый поток». Смысл этого флага в том, что вся программа Python завершается, когда остаются только фоновые потоки. Начальное значение наследуется от создающего потока. Флаг можно задать через свойство [`daemon`](https://python-all.ru/3.2/library/threading.html#threading.Thread.daemon).135136> **Примечание**137>138> Потоки-демоны при завершении работы останавливаются принудительно. Их ресурсы (такие как открытые файлы, транзакции базы данных и т.п.) могут быть освобождены некорректно. Если нужно, чтобы потоки завершались корректно, сделайте их недемоническими и используйте подходящий механизм сигнализации, например [`Event`](https://python-all.ru/3.2/library/threading.html#threading.Event).139140Существует объект «главный поток»; он соответствует начальному потоку управления в программе Python. Это не фоновый поток.141142Существует возможность создания «фиктивных объектов потоков». Это объекты потоков, соответствующие «внешним потокам», то есть потокам управления, запущенным вне модуля threading, например, напрямую из C-кода. Фиктивные объекты потоков имеют ограниченную функциональность; они всегда считаются живыми и демоническими, и к ним нельзя применить [`join()`](https://python-all.ru/3.2/library/threading.html#threading.Thread.join). Они никогда не удаляются, так как невозможно обнаружить завершение внешнего потока.143144#### `class threading.Thread(group=None, target=None, name=None, args=(), kwargs={})`145146Этот конструктор всегда следует вызывать с именованными аргументами. Аргументы:147148Параметр *group* должен быть `None`; зарезервирован для будущего расширения, когда будет реализован класс `ThreadGroup`.149150Параметр *target* – это вызываемый объект, который будет вызван методом [`run()`](https://python-all.ru/3.2/library/threading.html#threading.Thread.run). По умолчанию `None`, то есть ничего не вызывается.151152*name* – это имя потока. По умолчанию создаётся уникальное имя вида «Поток-*N*», где *N* – небольшое десятичное число.153154*args* – кортеж аргументов для вызова целевой функции. По умолчанию равен `()`.155156*kwargs* – это словарь именованных аргументов для вызова target. По умолчанию `{}`.157158Если подкласс переопределяет конструктор, он должен вызывать конструктор базового класса (`Thread.__init__()`) перед любыми другими действиями с потоком.159160#### `start()`161162Запускает выполнение потока.163164Этот метод должен вызываться не более одного раза для каждого объекта потока. Он организует вызов метода [`run()`](https://python-all.ru/3.2/library/threading.html#threading.Thread.run) объекта в отдельном потоке управления.165166Этот метод вызовет исключение [`RuntimeError`](https://python-all.ru/3.2/library/exceptions.html#RuntimeError), если его вызвать более одного раза для одного и того же объекта потока.167168#### `run()`169170Метод, представляющий действие потока.171172Вы можете переопределить этот метод в подклассе. Стандартный метод [`run()`](https://python-all.ru/3.2/library/threading.html#threading.Thread.run) вызывает вызываемый объект, переданный конструктору объекта как аргумент *target* (если он есть), с позиционными и именованными аргументами, взятыми из аргументов *args* и *kwargs* соответственно.173174#### `join(timeout=None)`175176Ожидает завершения потока. Этот метод блокирует вызывающий поток до тех пор, пока поток, для которого вызван метод [`join()`](https://python-all.ru/3.2/library/threading.html#threading.Thread.join), не завершится – либо нормально, либо из-за необработанного исключения – или пока не истечёт указанное время ожидания.177178Когда аргумент *timeout* присутствует и не равен `None`, он должен быть числом с плавающей точкой, задающим время ожидания операции в секундах (или долях секунды). Поскольку [`join()`](https://python-all.ru/3.2/library/threading.html#threading.Thread.join) всегда возвращает `None`, необходимо вызвать [`is_alive()`](https://python-all.ru/3.2/library/threading.html#threading.Thread.is_alive) после [`join()`](https://python-all.ru/3.2/library/threading.html#threading.Thread.join), чтобы определить, произошло ли истечение времени – если поток всё ещё жив, вызов [`join()`](https://python-all.ru/3.2/library/threading.html#threading.Thread.join) завершился по тайм-ауту.179180Если аргумент *timeout* отсутствует или равен `None`, операция будет блокироваться до завершения потока.181182К одному потоку можно применить [`join()`](https://python-all.ru/3.2/library/threading.html#threading.Thread.join) много раз.183184Вызов [`join()`](https://python-all.ru/3.2/library/threading.html#threading.Thread.join) вызывает исключение [`RuntimeError`](https://python-all.ru/3.2/library/exceptions.html#RuntimeError), если предпринимается попытка присоединения к текущему потоку, поскольку это привело бы к взаимоблокировке. Также является ошибкой вызов [`join()`](https://python-all.ru/3.2/library/threading.html#threading.Thread.join) для потока до его запуска, и такие попытки вызывают то же исключение.185186#### `name`187188Строка, используемая только для идентификации. Она не имеет семантического значения. Разным потокам можно задать одно и то же имя. Начальное имя устанавливается конструктором.189190#### `getName()`191192#### `setName()`193194Устаревший API геттера/сеттера для [`name`](https://python-all.ru/3.2/library/threading.html#threading.Thread.name); вместо этого используйте его напрямую как свойство.195196#### `ident`197198«Идентификатор потока» данного потока или `None`, если поток не был запущен. Это ненулевое целое число. Смотрите функцию [`_thread.get_ident()`](https://python-all.ru/3.2/library/_thread.html#_thread.get_ident). Идентификаторы потоков могут быть переиспользованы, когда поток завершается и создаётся новый поток. Идентификатор доступен даже после завершения потока.199200#### `is_alive()`201202Возвращает, жив ли поток.203204Этот метод возвращает `True` начиная непосредственно перед запуском метода [`run()`](https://python-all.ru/3.2/library/threading.html#threading.Thread.run) и до момента сразу после завершения метода [`run()`](https://python-all.ru/3.2/library/threading.html#threading.Thread.run). Функция модуля [`enumerate()`](https://python-all.ru/3.2/library/threading.html#threading.enumerate) возвращает список всех живых потоков.205206#### `daemon`207208Логическое значение, указывающее, является ли данный поток демоническим (True) или нет (False). Это значение должно быть установлено до вызова [`start()`](https://python-all.ru/3.2/library/threading.html#threading.Thread.start), иначе будет вызвано исключение [`RuntimeError`](https://python-all.ru/3.2/library/exceptions.html#RuntimeError). Его начальное значение наследуется от создающего потока; главный поток не является демоническим, и поэтому все потоки, созданные в главном потоке, по умолчанию имеют [`daemon`](https://python-all.ru/3.2/library/threading.html#threading.Thread.daemon) = `False`.209210Вся программа Python завершается, когда не остаётся ни одного живого потока, не являющегося демоном.211212#### `isDaemon()`213214#### `setDaemon()`215216Устаревший API геттера/сеттера для [`daemon`](https://python-all.ru/3.2/library/threading.html#threading.Thread.daemon); вместо этого используйте его напрямую как свойство.217218## 16.2.2. Объекты блокировки219220Примитивная блокировка – это синхронизационный примитив, который не принадлежит конкретному потоку в заблокированном состоянии. В Python это в настоящее время самый низкоуровневый доступный примитив синхронизации, реализованный непосредственно модулем расширения [`_thread`](https://python-all.ru/3.2/library/_thread.html#module-_thread).221222Примитивная блокировка находится в одном из двух состояний: «заблокировано» (locked) или «разблокировано» (unlocked). Она создаётся в разблокированном состоянии. Имеет два основных метода: [`acquire()`](https://python-all.ru/3.2/library/threading.html#threading.Lock.acquire) и [`release()`](https://python-all.ru/3.2/library/threading.html#threading.Lock.release). Когда состояние разблокировано, [`acquire()`](https://python-all.ru/3.2/library/threading.html#threading.Lock.acquire) переводит его в заблокированное и сразу возвращает управление. Когда состояние заблокировано, [`acquire()`](https://python-all.ru/3.2/library/threading.html#threading.Lock.acquire) блокируется до тех пор, пока вызов [`release()`](https://python-all.ru/3.2/library/threading.html#threading.Lock.release) из другого потока не переведёт его в разблокированное; после этого вызов [`acquire()`](https://python-all.ru/3.2/library/threading.html#threading.Lock.acquire) снова устанавливает заблокированное состояние и возвращает управление. Метод [`release()`](https://python-all.ru/3.2/library/threading.html#threading.Lock.release) следует вызывать только в заблокированном состоянии; он переводит состояние в разблокированное и немедленно возвращает управление. При попытке освободить разблокированную блокировку будет возбуждено исключение [`RuntimeError`](https://python-all.ru/3.2/library/exceptions.html#RuntimeError).223224Блокировки также поддерживают [*протокол контекстного менеджера*](https://python-all.ru/3.2/library/threading.html#with-locks).225226Когда несколько потоков заблокированы в вызове [`acquire()`](https://python-all.ru/3.2/library/threading.html#threading.Lock.acquire) в ожидании разблокировки состояния, только один поток продолжает работу после того, как вызов [`release()`](https://python-all.ru/3.2/library/threading.html#threading.Lock.release) переведёт состояние в разблокированное; какой именно из ожидающих потоков продолжит работу – не определено и может различаться в разных реализациях.227228Все методы выполняются атомарно.229230#### `Lock.acquire(blocking=True, timeout=-1)`231232Захватывает блокировку, блокирующую или неблокирующую.233234При вызове с аргументом *blocking*, установленным в `True` (по умолчанию), блокирует выполнение до тех пор, пока блокировка не будет разблокирована, после чего устанавливает её в заблокированное состояние и возвращает `True`.235236При вызове с аргументом *blocking*, установленным в `False`, блокировка не выполняется. Если вызов с *blocking*, установленным в `True`, привёл бы к блокировке, немедленно возвращается `False`; в противном случае блокировка устанавливается в заблокированное состояние и возвращается `True`.237238При вызове с вещественным аргументом *timeout*, установленным в положительное значение, блокируется не более чем на количество секунд, заданное *timeout*, и до тех пор, пока блокировка не может быть получена. Отрицательное значение аргумента *timeout* означает неограниченное ожидание. Не допускается указывать *timeout*, когда *blocking* равно False.239240Возвращаемое значение – `True`, если блокировка успешно захвачена, или `False` в противном случае (например, если истёк *тайм-аут*).241242Изменено в версии 3.2: Добавлен параметр *timeout*.243244Изменено в версии 3.2: Захват блокировок теперь может прерываться сигналами на POSIX.245246#### `Lock.release()`247248Освобождает блокировку. Может вызываться из любого потока, а не только из того, который захватил блокировку.249250Когда блокировка установлена, сбрасывает её в снятое состояние и возвращает управление. Если другие потоки заблокированы в ожидании освобождения блокировки, ровно одному из них разрешается продолжить работу.251252При вызове на разблокированной блокировке вызывается исключение `ThreadError`.253254Возвращаемое значение отсутствует.255256## 16.2.3. Объекты RLock257258Повторно входимая блокировка – это примитив синхронизации, который может быть захвачен одним и тем же потоком несколько раз. Внутри она использует понятия «поток-владелец» и «уровень рекурсии» в дополнение к состоянию «заблокировано/разблокировано», используемому простыми блокировками. В заблокированном состоянии блокировкой владеет какой-то поток; в разблокированном состоянии ею не владеет ни один поток.259260Для блокировки поток вызывает свой метод [`acquire()`](https://python-all.ru/3.2/library/threading.html#threading.RLock.acquire); этот метод возвращает управление, когда поток получает во владение блокировку. Для разблокировки поток вызывает свой метод [`release()`](https://python-all.ru/3.2/library/threading.html#threading.Lock.release). Пары вызовов [`acquire()`](https://python-all.ru/3.2/library/threading.html#threading.Lock.acquire)/[`release()`](https://python-all.ru/3.2/library/threading.html#threading.Lock.release) могут быть вложенными; только последний вызов [`release()`](https://python-all.ru/3.2/library/threading.html#threading.Lock.release) (самый внешний [`release()`](https://python-all.ru/3.2/library/threading.html#threading.Lock.release)) переводит блокировку в разблокированное состояние и позволяет другому потоку, заблокированному в [`acquire()`](https://python-all.ru/3.2/library/threading.html#threading.Lock.acquire), продолжить работу.261262Рекурсивные блокировки также поддерживают [*протокол контекстного менеджера*](https://python-all.ru/3.2/library/threading.html#with-locks).263264#### `RLock.acquire(blocking=True, timeout=-1)`265266Захватывает блокировку, блокирующую или неблокирующую.267268При вызове без аргументов: если этот поток уже владеет блокировкой, увеличить уровень рекурсии на единицу и немедленно вернуться. В противном случае, если блокировкой владеет другой поток, блокироваться до тех пор, пока блокировка не будет освобождена. Как только блокировка освобождена (не принадлежит ни одному потоку), захватить владение, установить уровень рекурсии в единицу и вернуться. Если несколько потоков заблокированы в ожидании освобождения блокировки, только один из них сможет захватить владение. В этом случае возвращаемого значения нет.269270При вызове с аргументом *blocking*, установленным в true, делает то же самое, что и при вызове без аргументов, и возвращает true.271272При вызове с аргументом *blocking*, установленным в false, не блокируется. Если вызов без аргументов привёл бы к блокировке, немедленно возвращает false; в противном случае делает то же самое, что и при вызове без аргументов, и возвращает true.273274При вызове с аргументом *timeout* типа float, установленным в положительное значение, блокируется не более чем на число секунд, указанное в *timeout*, и до тех пор, пока блокировка не будет получена. Возвращает True, если блокировка получена, и False, если истекло время ожидания.275276Изменено в версии 3.2: Добавлен параметр *timeout*.277278#### `RLock.release()`279280Освобождает блокировку, уменьшая уровень рекурсии. Если после уменьшения он становится нулевым, сбрасывает блокировку в разблокированное состояние (не принадлежит ни одному потоку), и, если другие потоки заблокированы в ожидании освобождения блокировки, ровно одному из них разрешается продолжить. Если после уменьшения уровень рекурсии всё ещё ненулевой, блокировка остаётся заблокированной и принадлежит вызывающему потоку.281282Вызывайте этот метод только тогда, когда вызывающий поток владеет блокировкой. Исключение [`RuntimeError`](https://python-all.ru/3.2/library/exceptions.html#RuntimeError) возбуждается, если этот метод вызван, когда блокировка разблокирована.283284Возвращаемое значение отсутствует.285286## 16.2.4. Объекты Condition287288Переменная условия всегда связана с какой-либо блокировкой; её можно передать, или же она будет создана по умолчанию. Передача блокировки полезна, когда несколько переменных условия должны совместно использовать одну и ту же блокировку. Блокировка является частью объекта условия: не нужно отслеживать её отдельно.289290Переменная условия подчиняется [*протоколу контекстного менеджера*](https://python-all.ru/3.2/library/threading.html#with-locks): использование оператора `with` захватывает связанную блокировку на время вложенного блока. Методы [`acquire()`](https://python-all.ru/3.2/library/threading.html#threading.Condition.acquire) и [`release()`](https://python-all.ru/3.2/library/threading.html#threading.Condition.release) также вызывают соответствующие методы связанной блокировки.291292Другие методы должны вызываться только при удержании связанной блокировки. Метод [`wait()`](https://python-all.ru/3.2/library/threading.html#threading.Condition.wait) освобождает блокировку и затем блокируется, пока другой поток не пробудит его вызовом [`notify()`](https://python-all.ru/3.2/library/threading.html#threading.Condition.notify) или [`notify_all()`](https://python-all.ru/3.2/library/threading.html#threading.Condition.notify_all). После пробуждения [`wait()`](https://python-all.ru/3.2/library/threading.html#threading.Condition.wait) повторно захватывает блокировку и возвращает управление. Также можно указать тайм-аут.293294Метод [`notify()`](https://python-all.ru/3.2/library/threading.html#threading.Condition.notify) пробуждает один из потоков, ожидающих на данной условной переменной (если такие есть). Метод [`notify_all()`](https://python-all.ru/3.2/library/threading.html#threading.Condition.notify_all) пробуждает все потоки, ожидающие на условной переменной.295296Примечание: методы [`notify()`](https://python-all.ru/3.2/library/threading.html#threading.Condition.notify) и [`notify_all()`](https://python-all.ru/3.2/library/threading.html#threading.Condition.notify_all) не освобождают блокировку; это означает, что пробуждённый поток (или потоки) не вернутся из своего вызова [`wait()`](https://python-all.ru/3.2/library/threading.html#threading.Condition.wait) немедленно, а только тогда, когда поток, вызвавший [`notify()`](https://python-all.ru/3.2/library/threading.html#threading.Condition.notify) или [`notify_all()`](https://python-all.ru/3.2/library/threading.html#threading.Condition.notify_all), окончательно откажется от владения блокировкой.297298### 16.2.4.1. Использование299300Типичный стиль программирования с использованием условных переменных заключается в том, чтобы использовать блокировку для синхронизации доступа к некоторому общему состоянию; потоки, заинтересованные в определённом изменении состояния, вызывают [`wait()`](https://python-all.ru/3.2/library/threading.html#threading.Condition.wait) многократно, пока не увидят желаемое состояние, тогда как потоки, изменяющие состояние, вызывают [`notify()`](https://python-all.ru/3.2/library/threading.html#threading.Condition.notify) или [`notify_all()`](https://python-all.ru/3.2/library/threading.html#threading.Condition.notify_all), когда они изменяют состояние таким образом, что оно может оказаться желаемым для одного из ожидающих потоков. Например, следующий код представляет собой обобщённую ситуацию «производитель-потребитель» с неограниченной ёмкостью буфера:301302```python303# Потребить один элемент304with cv:305    while not an_item_is_available():306        cv.wait()307    get_an_available_item()308309# Произвести один элемент310with cv:311    make_an_item_available()312    cv.notify()313```314315Цикл `while`, проверяющий условие приложения, необходим, потому что [`wait()`](https://python-all.ru/3.2/library/threading.html#threading.Condition.wait) может вернуть управление спустя произвольно долгое время, и условие, которое привело к вызову [`notify()`](https://python-all.ru/3.2/library/threading.html#threading.Condition.notify), может уже не выполняться. Это присуще многопоточному программированию. Метод [`wait_for()`](https://python-all.ru/3.2/library/threading.html#threading.Condition.wait_for) можно использовать для автоматизации проверки условия, что упрощает вычисление тайм-аутов:316317```python318# Потребить элемент319with cv:320    cv.wait_for(an_item_is_available)321    get_an_available_item()322```323324При выборе между [`notify()`](https://python-all.ru/3.2/library/threading.html#threading.Condition.notify) и [`notify_all()`](https://python-all.ru/3.2/library/threading.html#threading.Condition.notify_all) учитывайте, может ли одно изменение состояния быть интересно только одному или нескольким ожидающим потокам. Например, в типичной ситуации «производитель-потребитель» добавление одного элемента в буфер требует пробуждения только одного потока-потребителя.325326### 16.2.4.2. Интерфейс327328#### `class threading.Condition(lock=None)`329330Если аргумент *блокировка* задан и не равен `None`, то он должен быть объектом [`блокировка`](https://python-all.ru/3.2/library/threading.html#threading.Lock) или [`RLock`](https://python-all.ru/3.2/library/threading.html#threading.RLock) и использоваться в качестве базовой блокировки. В противном случае создаётся новый объект [`RLock`](https://python-all.ru/3.2/library/threading.html#threading.RLock), который используется как базовая блокировка.331332#### `acquire(*args)`333334Захватывает базовую блокировку. Этот метод вызывает соответствующий метод базовой блокировки; возвращаемое значение – то, что возвращает этот метод.335336#### `release()`337338Освобождает базовую блокировку. Этот метод вызывает соответствующий метод базовой блокировки; возвращаемое значение отсутствует.339340#### `wait(timeout=None)`341342Ожидает до получения уведомления или до истечения тайм-аута. Если вызывающий поток не захватил блокировку на момент вызова этого метода, возбуждается исключение [`RuntimeError`](https://python-all.ru/3.2/library/exceptions.html#RuntimeError).343344Этот метод освобождает базовую блокировку, а затем блокируется до тех пор, пока не будет пробуждён вызовом [`notify()`](https://python-all.ru/3.2/library/threading.html#threading.Condition.notify) или [`notify_all()`](https://python-all.ru/3.2/library/threading.html#threading.Condition.notify_all) для той же условной переменной из другого потока, или пока не наступит опциональный тайм-аут. После пробуждения или истечения тайм-аута он повторно захватывает блокировку и возвращает управление.345346Если аргумент *timeout* присутствует и не равен `None`, то он должен быть числом с плавающей запятой, указывающим тайм-аут для операции в секундах (или долях секунды).347348Если базовая блокировка является объектом [`RLock`](https://python-all.ru/3.2/library/threading.html#threading.RLock), то она не освобождается с помощью его метода [`release()`](https://python-all.ru/3.2/library/threading.html#threading.Condition.release), поскольку этот метод может фактически не разблокировать блокировку, если она была захвачена несколько раз рекурсивно. Вместо этого используется внутренний интерфейс класса [`RLock`](https://python-all.ru/3.2/library/threading.html#threading.RLock), который действительно разблокирует её, даже если она была рекурсивно захвачена несколько раз. Затем другой внутренний интерфейс восстанавливает уровень рекурсии при повторном захвате блокировки.349350Возвращаемое значение равно `True`, если только не истёк заданный *тайм-аут*; в этом случае возвращается `False`.351352Изменено в версии 3.2: Ранее метод всегда возвращал `None`.353354#### `wait_for(predicate, timeout=None)`355356Ожидание, пока условие не станет истинным (True). *predicate* должен быть вызываемым объектом, результат которого будет интерпретироваться как логическое значение. Можно указать *timeout*, задающий максимальное время ожидания.357358Этот вспомогательный метод может многократно вызывать [`wait()`](https://python-all.ru/3.2/library/threading.html#threading.Condition.wait), пока предикат не будет выполнен или пока не истечет время ожидания. Возвращаемое значение – это последнее возвращаемое значение предиката, и оно будет равно `False`, если метод завершился по тайм-ауту.359360Если не учитывать возможность тайм-аута, вызов этого метода примерно эквивалентен следующему коду:361362```python363while not predicate():364    cv.wait()365```366367Поэтому применяются те же правила, что и для [`wait()`](https://python-all.ru/3.2/library/threading.html#threading.Condition.wait): блокировка должна быть захвачена при вызове и повторно захватывается при возврате. Предикат вычисляется при захваченной блокировке.368369Новое в версии 3.2.370371#### `notify(n=1)`372373По умолчанию пробуждает один поток, ожидающий на этом условии, если таковой имеется. Если вызывающий поток не захватил блокировку при вызове этого метода, возникает исключение [`RuntimeError`](https://python-all.ru/3.2/library/exceptions.html#RuntimeError).374375Этот метод пробуждает не более *n* потоков, ожидающих на переменной условия; если ни один поток не ожидает, он ничего не делает.376377Текущая реализация пробуждает ровно *n* потоков, если ожидает не менее *n* потоков. Однако полагаться на такое поведение небезопасно. В будущем оптимизированная реализация может иногда пробуждать более *n* потоков.378379Примечание: пробужденный поток фактически не возвращается из своего вызова [`wait()`](https://python-all.ru/3.2/library/threading.html#threading.Condition.wait), пока не сможет повторно захватить блокировку. Поскольку [`notify()`](https://python-all.ru/3.2/library/threading.html#threading.Condition.notify) не освобождает блокировку, это должен сделать вызвавший её поток.380381#### `notify_all()`382383Пробуждает все потоки, ожидающие на этом условии. Этот метод действует как [`notify()`](https://python-all.ru/3.2/library/threading.html#threading.Condition.notify), но пробуждает все ожидающие потоки вместо одного. Если вызывающий поток не захватил блокировку при вызове этого метода, возникает исключение [`RuntimeError`](https://python-all.ru/3.2/library/exceptions.html#RuntimeError).384385## 16.2.5. Объекты семафоров386387Это один из старейших примитивов синхронизации в истории информатики, изобретенный ранним нидерландским учёным Эдсгером В. Дейкстрой (он использовал имена `P()` и `V()` вместо [`acquire()`](https://python-all.ru/3.2/library/threading.html#threading.Semaphore.acquire) и [`release()`](https://python-all.ru/3.2/library/threading.html#threading.Semaphore.release)).388389Семафор управляет внутренним счётчиком, который уменьшается при каждом вызове [`acquire()`](https://python-all.ru/3.2/library/threading.html#threading.Semaphore.acquire) и увеличивается при каждом вызове [`release()`](https://python-all.ru/3.2/library/threading.html#threading.Semaphore.release). Счётчик никогда не может стать меньше нуля; когда [`acquire()`](https://python-all.ru/3.2/library/threading.html#threading.Semaphore.acquire) обнаруживает, что он равен нулю, он блокируется, ожидая, пока другой поток вызовет [`release()`](https://python-all.ru/3.2/library/threading.html#threading.Semaphore.release).390391Семафоры также поддерживают [*протокол менеджера контекста*](https://python-all.ru/3.2/library/threading.html#with-locks).392393#### `class threading.Semaphore(value=1)`394395Необязательный аргумент задаёт начальное *value* для внутреннего счётчика; по умолчанию оно равно `1`. Если указанное *value* меньше 0, возникает исключение [`ValueError`](https://python-all.ru/3.2/library/exceptions.html#ValueError).396397#### `acquire(blocking=True, timeout=None)`398399Захватывает семафор.400401При вызове без аргументов: если внутренний счётчик при входе больше нуля, уменьшить его на единицу и сразу вернуться. Если он равен нулю, заблокироваться, ожидая, пока другой поток вызовет [`release()`](https://python-all.ru/3.2/library/threading.html#threading.Semaphore.release), чтобы сделать его больше нуля. Это делается с надлежащей взаимной блокировкой, так что если несколько вызовов [`acquire()`](https://python-all.ru/3.2/library/threading.html#threading.Semaphore.acquire) заблокированы, [`release()`](https://python-all.ru/3.2/library/threading.html#threading.Semaphore.release) пробудит ровно один из них. Реализация может выбрать любой случайным образом, поэтому на порядок пробуждения заблокированных потоков полагаться не следует. Возвращает true (или блокируется на неопределённый срок).402403При вызове с *blocking*, установленным в false, не блокироваться. Если вызов без аргумента заблокировался бы, немедленно вернуть false; в противном случае сделать то же самое, что и при вызове без аргументов, и вернуть true.404405При вызове с *timeout*, отличным от None, он будет блокироваться не более *timeout* секунд. Если acquire не завершится успешно за это время, вернуть false. В противном случае вернуть true.406407Изменено в версии 3.2: Добавлен параметр *timeout*.408409#### `release()`410411Освобождает семафор, увеличивая внутренний счётчик на единицу. Когда он был равен нулю при входе и другой поток ожидает, когда он снова станет больше нуля, пробуждает этот поток.412413### 16.2.5.1. [`Semaphore`](https://python-all.ru/3.2/library/threading.html#threading.Semaphore) Пример414415Семафоры часто используются для защиты ресурсов с ограниченной ёмкостью, например, сервера базы данных. В любой ситуации, когда размер ресурса фиксирован, следует использовать ограниченный семафор. Перед запуском рабочих потоков главный поток инициализирует семафор:416417```python418maxconnections = 5419...420pool_sema = BoundedSemaphore(value=maxconnections)421```422423После запуска рабочие потоки вызывают методы acquire и release семафора, когда им нужно подключиться к серверу:424425```python426with pool_sema:427    conn = connectdb()428    try:429        ... use connection ...430    finally:431        conn.close()432```433434Использование ограниченного семафора снижает вероятность того, что ошибка программирования, приводящая к освобождению семафора большее количество раз, чем его захват, останется незамеченной.435436## 16.2.6. Объекты событий437438Это один из простейших механизмов взаимодействия между потоками: один поток сигнализирует о событии, а другие потоки ожидают его.439440Объект-событие управляет внутренним флагом, который может быть установлен в true методом [`set()`](https://python-all.ru/3.2/library/threading.html#threading.Event.set) и сброшен в false методом [`clear()`](https://python-all.ru/3.2/library/threading.html#threading.Event.clear). Метод [`wait()`](https://python-all.ru/3.2/library/threading.html#threading.Event.wait) блокируется, пока флаг не станет true.441442#### `class threading.Event`443444Внутренний флаг изначально равен false.445446#### `is_set()`447448Возвращает true тогда и только тогда, когда внутренний флаг равен true.449450#### `set()`451452Устанавливает внутренний флаг в true. Все потоки, ожидающие его установки в true, пробуждаются. Потоки, которые вызывают [`wait()`](https://python-all.ru/3.2/library/threading.html#threading.Event.wait) после того, как флаг уже true, не будут блокироваться вообще.453454#### `clear()`455456Сбрасывает внутренний флаг в false. После этого потоки, вызывающие [`wait()`](https://python-all.ru/3.2/library/threading.html#threading.Event.wait), будут блокироваться до тех пор, пока не будет вызван [`set()`](https://python-all.ru/3.2/library/threading.html#threading.Event.set), чтобы снова установить флаг в true.457458#### `wait(timeout=None)`459460Блокируется, пока внутренний флаг не станет true. Если при входе флаг уже true, вернуться немедленно. В противном случае блокироваться до тех пор, пока другой поток не вызовет [`set()`](https://python-all.ru/3.2/library/threading.html#threading.Event.set), чтобы установить флаг в true, или пока не истечет необязательный тайм-аут.461462Если аргумент timeout присутствует и не равен `None`, он должен быть числом с плавающей точкой, задающим таймаут для операции в секундах (или долях секунды).463464Этот метод возвращает True тогда и только тогда, когда внутренний флаг был установлен в True (до вызова wait или в процессе ожидания). Таким образом, он всегда возвращает `True`, за исключением случаев, когда указан таймаут и его время истекло.465466Изменено в версии 3.1: Ранее метод всегда возвращал `None`.467468## 16.2.7. Объекты таймеров469470Этот класс представляет действие, которое должно быть выполнено только после того, как пройдет определенное время – таймер. [`Timer`](https://python-all.ru/3.2/library/threading.html#threading.Timer) является подклассом [`Thread`](https://python-all.ru/3.2/library/threading.html#threading.Thread) и, таким образом, служит примером создания пользовательских потоков.471472Таймеры запускаются, как и потоки, вызовом метода `start()`. Таймер можно остановить (до начала его действия) вызовом метода `cancel()`. Интервал, который таймер будет ждать перед выполнением своего действия, может не совпадать в точности с интервалом, указанным пользователем.473474Например:475476```python477def hello():478    print("hello, world")479480t = Timer(30.0, hello)481t.start() # через 30 секунд будет выведено "hello, world"482```483484#### `class threading.Timer(interval, function, args=[], kwargs={})`485486Создаёт таймер, который выполнит *function* с аргументами *args* и именованными аргументами *kwargs* по прошествии *interval* секунд.487488#### `cancel()`489490Останавливает таймер и отменяет выполнение его действия. Это сработает, только если таймер всё ещё находится в стадии ожидания.491492## 16.2.8. Объекты барьеров493494Новое в версии 3.2.495496Этот класс предоставляет простой примитив синхронизации для использования фиксированным количеством потоков, которым нужно дождаться друг друга. Каждый поток пытается пройти барьер, вызывая метод [`wait()`](https://python-all.ru/3.2/library/threading.html#threading.Barrier.wait), и блокируется до тех пор, пока все потоки не сделают вызов. В этот момент потоки освобождаются одновременно.497498Барьер можно использовать повторно любое количество раз для того же числа потоков.499500В качестве примера приведён простой способ синхронизации потоков клиента и сервера:501502```python503b = Barrier(2, timeout=5)504505def server():506    start_server()507    b.wait()508    while True:509        connection = accept_connection()510        process_server_connection(connection)511512def client():513    b.wait()514    while True:515        connection = make_connection()516        process_client_connection(connection)517```518519#### `class threading.Barrier(parties, action=None, timeout=None)`520521Создает объект барьера для *parties* потоков. Параметр *action*, если указан, должен быть вызываемым объектом, который будет вызван одним из потоков при их освобождении. *timeout* – это значение таймаута по умолчанию, если оно не задано для метода [`wait()`](https://python-all.ru/3.2/library/threading.html#threading.Barrier.wait).522523#### `wait(timeout=None)`524525Пройти барьер. Когда все потоки-участники барьера вызовут эту функцию, они все освобождаются одновременно. Если указан *timeout*, он используется с приоритетом перед любым значением, переданным конструктору класса.526527Возвращаемое значение – целое число в диапазоне от 0 до *parties* – 1, различное для каждого потока. Это можно использовать для выбора потока, который выполнит специальные вспомогательные действия, например:528529```python530i = barrier.wait()531if i == 0:532    # Выводить это должен только один поток533    print("passed the barrier")534```535536Если конструктору был передан *action*, один из потоков вызовет его перед освобождением. Если этот вызов вызовет ошибку, барьер переводится в состояние сбоя.537538Если вызов истекает по таймауту, барьер переводится в сломанное состояние.539540Этот метод может возбудить исключение [`BrokenBarrierError`](https://python-all.ru/3.2/library/threading.html#threading.BrokenBarrierError), если барьер был поврежден или сброшен, пока поток ожидает.541542#### `reset()`543544Возвращает барьер в исходное пустое состояние. Все потоки, ожидающие на нем, получат исключение [`BrokenBarrierError`](https://python-all.ru/3.2/library/threading.html#threading.BrokenBarrierError).545546Обратите внимание, что использование этой функции может потребовать внешней синхронизации, если есть другие потоки, состояние которых неизвестно. Если барьер сломан, возможно, лучше просто оставить его и создать новый.547548#### `abort()`549550Переводит барьер в поврежденное состояние. Это приводит к тому, что любые текущие или будущие вызовы [`wait()`](https://python-all.ru/3.2/library/threading.html#threading.Barrier.wait) завершаются ошибкой с [`BrokenBarrierError`](https://python-all.ru/3.2/library/threading.html#threading.BrokenBarrierError). Используйте это, например, если один из потоков необходимо прервать, чтобы избежать взаимоблокировки приложения.551552Возможно, предпочтительнее просто создать барьер с разумным значением *timeout*, чтобы автоматически защититься от сбоя одного из потоков.553554#### `parties`555556Количество потоков, необходимое для прохождения барьера.557558#### `n_waiting`559560Количество потоков, ожидающих в данный момент на барьере.561562#### `broken`563564Булево значение, которое равно `True`, если барьер находится в поврежденном состоянии.565566#### `exception threading.BrokenBarrierError`567568Это исключение, являющееся подклассом [`RuntimeError`](https://python-all.ru/3.2/library/exceptions.html#RuntimeError), возбуждается, когда объект [`Barrier`](https://python-all.ru/3.2/library/threading.html#threading.Barrier) сбрасывается или повреждается.569570## 16.2.9. Использование блокировок, условий и семафоров в операторе [`with`](https://python-all.ru/3.2/reference/compound_stmts.html#with)571572Все объекты, предоставляемые этим модулем, которые имеют методы `acquire()` и `release()`, могут использоваться как контекстные менеджеры в операторе [`with`](https://python-all.ru/3.2/reference/compound_stmts.html#with). Метод `acquire()` будет вызван при входе в блок, а `release()` – при выходе из блока. Следовательно, следующий фрагмент:573574```python575with some_lock:576    # выполнить какие-то действия...577```578579эквивалентно:580581```python582some_lock.acquire()583try:584    # выполнить какие-то действия...585finally:586    some_lock.release()587```588589В настоящее время объекты [`Lock`](https://python-all.ru/3.2/library/threading.html#threading.Lock), [`RLock`](https://python-all.ru/3.2/library/threading.html#threading.RLock), [`Condition`](https://python-all.ru/3.2/library/threading.html#threading.Condition), [`Semaphore`](https://python-all.ru/3.2/library/threading.html#threading.Semaphore) и [`BoundedSemaphore`](https://python-all.ru/3.2/library/threading.html#threading.BoundedSemaphore) могут использоваться как контекстные менеджеры в операторе [`with`](https://python-all.ru/3.2/reference/compound_stmts.html#with).590591## 16.2.10. Импортирование в многопоточном коде592593Хотя механизм импорта потокобезопасен, есть два ключевых ограничения для импорта из потоков, вытекающие из внутренних особенностей реализации потокобезопасности:594595- Во-первых, за исключением главного модуля, импорт не должен вызывать побочный эффект в виде создания нового потока с последующим ожиданием этого потока любым способом. Несоблюдение этого ограничения может привести к взаимоблокировке, если созданный поток прямо или косвенно попытается импортировать модуль.596- Во-вторых, все попытки импорта должны быть завершены до того, как интерпретатор начнёт завершение работы. Проще всего этого добиться, выполняя импорт только из недемоновых потоков, созданных через модуль threading. Потоки-демоны и потоки, созданные напрямую с помощью модуля thread, потребуют какой-либо иной синхронизации, чтобы гарантировать, что они не будут пытаться выполнять импорт после начала завершения работы интерпретатора. Несоблюдение этого ограничения приведёт к периодическим исключениям и сбоям при завершении работы интерпретатора (поскольку поздние попытки импорта пытаются получить доступ к механизмам, которые уже находятся в недопустимом состоянии).597