# Примітиви синхронізації

Вихідний код: Lib/asyncio/locks.py

Примітиви синхронізації asyncio розроблені таким чином, щоб бути подібними до модулів `threading` з двома важливими застереженнями:

- примітиви asyncio не є потокобезпечними, тому їх не слід використовувати для синхронізації потоків ОС (для цього використовуйте `threading`);

- методи цих примітивів синхронізації не приймають аргумент timeout; використовуйте функцію `asyncio.wait_for()` для виконання операцій із тайм-аутами.

asyncio має такі базові примітиви синхронізації:

- `Lock`

- `Event`

- `Condition`

- `Semaphore`

- `BoundedSemaphore`

- `Barrier`

## Замок

class asyncio.Lock

  Реалізує блокування м’ютексу для асинхронних завдань. Небезпечно для потоків.

  Асинхронне блокування можна використовувати, щоб гарантувати ексклюзивний доступ до спільного ресурсу.

  Найкращим способом використання Lock є оператор `async with`:

      lock = asyncio.Lock()

      # ... later
      async with lock:
          # access shared state

  що еквівалентно:

      lock = asyncio.Lock()

      # ... later
      await lock.acquire()
      try:
          # access shared state
      finally:
          lock.release()

  Змінено в версії 3.10: Видалено параметр loop.

  async acquire()

    Придбайте замок.

    Цей метод очікує, поки блокування буде розблоковано, встановлює його на заблоковано та повертає `True`.

    Якщо в `acquire()` заблоковано більше ніж одну співпрограму, яка очікує розблокування блокування, зрештою виконується лише одна співпрограма.

    Отримання блокування є чесним: співпрограма, яка продовжується, буде першою співпрограмою, яка почала очікувати на блокування.

  release()

    Відпустіть замок.

    Коли замок заблоковано, скиньте його на розблоковано та поверніться.

    Якщо блокування розблоковано, виникає `RuntimeError`.

  locked()

    Повертає `True`, якщо блокування заблоковано.

## Подія

class asyncio.Event

  Об’єкт події. Небезпечно для потоків.

  Асинхронну подію можна використовувати для сповіщення кількох асинхронних завдань про те, що сталася якась подія.

  Об’єкт Event керує внутрішнім прапором, який можна встановити на true за допомогою методу `set()` і скинути на false за допомогою методу `clear()`. Метод `wait()` блокується, доки прапор не буде встановлено на true. Спочатку для прапора встановлено значення false.

  Змінено в версії 3.10: Видалено параметр loop.

  Приклад:

      async def waiter(event):
          print('waiting for it ...')
          await event.wait()
          print('... got it!')

      async def main():
          # Create an Event object.
          event = asyncio.Event()

          # Spawn a Task to wait until 'event' is set.
          waiter_task = asyncio.create_task(waiter(event))

          # Sleep for 1 second and set the event.
          await asyncio.sleep(1)
          event.set()

          # Wait until the waiter task is finished.
          await waiter_task

      asyncio.run(main())

  async wait()

    Дочекайтеся встановлення події.

    Якщо подія встановлена, негайно поверніть `True`. Інакше заблокуйте, доки інше завдання не викличе `set()`.

  set()

    Встановити подію.

    Усі завдання, які очікують встановлення події, будуть негайно активовані.

  clear()

    Очистити (скасувати) подію.

    Subsequent tasks awaiting on `wait()` will now block until the `set()` method is called again.

  is_set()

    Повертає `True`, якщо подія встановлена.

## Хвороба

class asyncio.Condition(lock=None)

  Об’єкт Condition. Небезпечно для потоків.

  Примітив асинхронної умови може використовуватися завданням для очікування настання певної події та отримання ексклюзивного доступу до спільного ресурсу.

  По суті, об’єкт Condition поєднує функціональні можливості `Event` і `Lock`. Кілька об’єктів Condition можуть використовувати один Lock, що дозволяє координувати ексклюзивний доступ до спільного ресурсу між різними завданнями, зацікавленими в певних станах цього спільного ресурсу.

  Додатковий аргумент lock має бути об’єктом `Lock` або `None`. В останньому випадку новий об’єкт Lock створюється автоматично.

  Змінено в версії 3.10: Видалено параметр loop.

  Найкращим способом використання умови є оператор `async with`:

      cond = asyncio.Condition()

      # ... later
      async with cond:
          await cond.wait()

  що еквівалентно:

      cond = asyncio.Condition()

      # ... later
      await cond.acquire()
      try:
          await cond.wait()
      finally:
          cond.release()

  async acquire()

    Отримайте основний замок.

    Цей метод чекає, доки базове блокування розблокується, встановлює його на locked і повертає `True`.

  notify(n=1)

    Wake up n tasks (1 by default) waiting on this condition. If fewer than n tasks are waiting they are all awakened.

    Блокування має бути отримано перед викликом цього методу та звільнено незабаром після цього. У разі виклику з розблокованим блокуванням виникає помилка `RuntimeError`.

  locked()

    Повертає `True`, якщо основне блокування отримано.

  notify_all()

    Розбудіть усі завдання, що очікують за цієї умови.

    Цей метод діє як `notify()`, але активує всі завдання, що очікують.

    Блокування має бути отримано перед викликом цього методу та звільнено незабаром після цього. У разі виклику з розблокованим блокуванням виникає помилка `RuntimeError`.

  release()

    Звільніть базовий замок.

    Під час виклику для розблокованого блокування виникає `RuntimeError`.

  async wait()

    Дочекайтеся повідомлення.

    Якщо завдання, що викликає, не отримало блокування під час виклику цього методу, виникає `RuntimeError`.

    Цей метод знімає основне блокування, а потім блокує, доки його не розбудить виклик `notify()` або `notify_all()`. Після пробудження умова знову блокується, і цей метод повертає `True`.

    Note that a task may return from this call spuriously, which is why the caller should always re-check the state and be prepared to `wait()` again. For this reason, you may prefer to use `wait_for()` instead.

  async wait_for(predicate)

    Зачекайте, поки предикат стане true.

    The predicate must be a callable which result will be interpreted as a boolean value. The method will repeatedly `wait()` until the predicate evaluates to true. The final value is the return value.

## Семафор

class asyncio.Semaphore(value=1)

  Об’єкт Semaphore. Небезпечно для потоків.

  Семафор керує внутрішнім лічильником, який зменшується при кожному виклику `acquire()` і збільшується при кожному виклику `release()`. Лічильник ніколи не може опускатися нижче нуля; коли `acquire()` виявляє, що він дорівнює нулю, він блокується, чекаючи, поки якесь завдання викличе `release()`.

  Необов’язковий аргумент value дає початкове значення для внутрішнього лічильника (`1` за замовчуванням). Якщо вказане значення менше ніж `0`, виникає `ValueError`.

  Змінено в версії 3.10: Видалено параметр loop.

  Кращим способом використання семафора є оператор `async with`:

      sem = asyncio.Semaphore(10)

      # ... later
      async with sem:
          # work with shared resource

  що еквівалентно:

      sem = asyncio.Semaphore(10)

      # ... later
      await sem.acquire()
      try:
          # work with shared resource
      finally:
          sem.release()

  async acquire()

    Придбайте семафор.

    Якщо внутрішній лічильник більший за нуль, зменште його на одиницю та негайно поверніть `True`. Якщо він дорівнює нулю, дочекайтеся виклику `release()` і поверніть `True`.

  locked()

    Повертає `True`, якщо семафор не може бути отриманий негайно.

  release()

    Відпустіть семафор, збільшивши внутрішній лічильник на одиницю. Може розбудити завдання, яке очікує отримання семафора.

    На відміну від `BoundedSemaphore`, `Semaphore` дозволяє робити більше викликів `release()`, ніж викликів `acquire()`.

## Обмежений семафор

class asyncio.BoundedSemaphore(value=1)

  Обмежений семафорний об’єкт. Небезпечно для потоків.

  Обмежений семафор — це версія `Semaphore`, яка викликає `ValueError` у `release()`, якщо він збільшує внутрішній лічильник вище початкового значення.

  Змінено в версії 3.10: Видалено параметр loop.

## Barrier

class asyncio.Barrier(parties)

  A barrier object. Not thread-safe.

  A barrier is a simple synchronization primitive that allows to block until parties number of tasks are waiting on it. Tasks can wait on the `wait()` method and would be blocked until the specified number of tasks end up waiting on `wait()`. At that point all of the waiting tasks would unblock simultaneously.

  `async with` can be used as an alternative to awaiting on `wait()`.

  The barrier can be reused any number of times.

  Приклад:

      async def example_barrier():
         # barrier with 3 parties
         b = asyncio.Barrier(3)

         # create 2 new waiting tasks
         asyncio.create_task(b.wait())
         asyncio.create_task(b.wait())

         await asyncio.sleep(0)
         print(b)

         # The third .wait() call passes the barrier
         await b.wait()
         print(b)
         print("barrier passed")

         await asyncio.sleep(0)
         print(b)

      asyncio.run(example_barrier())

  Result of this example is:

      <asyncio.locks.Barrier object at 0x... [filling, waiters:2/3]>
      <asyncio.locks.Barrier object at 0x... [draining, waiters:0/3]>
      barrier passed
      <asyncio.locks.Barrier object at 0x... [filling, waiters:0/3]>

  Added in version 3.11.

  async wait()

    Pass the barrier. When all the tasks party to the barrier have called this function, they are all unblocked simultaneously.

    When a waiting or blocked task in the barrier is cancelled, this task exits the barrier which stays in the same state. If the state of the barrier is «filling», the number of waiting task decreases by 1.

    The return value is an integer in the range of 0 to `parties-1`, different for each task. This can be used to select a task to do some special housekeeping, e.g.:

        ...
        async with barrier as position:
           if position == 0:
              # Only one task prints this
              print('End of *draining phase*')

    This method may raise a `BrokenBarrierError` exception if the barrier is broken or reset while a task is waiting. It could raise a `CancelledError` if a task is cancelled.

  async reset()

    Return the barrier to the default, empty state. Any tasks waiting on it will receive the `BrokenBarrierError` exception.

    If a barrier is broken it may be better to just leave it and create a new one.

  async abort()

    Put the barrier into a broken state. This causes any active or future calls to `wait()` to fail with the `BrokenBarrierError`. Use this for example if one of the tasks needs to abort, to avoid infinite waiting tasks.

  parties

    The number of tasks required to pass the barrier.

  n_waiting

    The number of tasks currently waiting in the barrier while filling.

  broken

    Логічне значення, яке має значення `True`, якщо бар’єр знаходиться в зламаному стані.

exception asyncio.BrokenBarrierError

  Цей виняток, підклас `RuntimeError`, виникає, коли об’єкт `Barrier` скидається або зламано.

Змінено в версії 3.9: Отримання блокування за допомогою оператора `await lock` або `yield from lock` та/або `with` (`with await lock`, `with (yield from lock)`) було видалено . Натомість використовуйте `async with lock`.