Debian Codegraph @

Doc/library/asyncio-sync.rst

raw
1 .. currentmodule:: asyncio
2
3 .. _asyncio-sync:
4
5 ==========================
6 Synchronization Primitives
7 ==========================
8
9 **Source code:** :source:`Lib/asyncio/locks.py`
10
11 -----------------------------------------------
12
13 asyncio synchronization primitives are designed to be similar to
14 those of the :mod:`threading` module with two important caveats:
15
16 * asyncio primitives are not thread-safe, therefore they should not
17 be used for OS thread synchronization (use :mod:`threading` for
18 that);
19
20 * methods of these synchronization primitives do not accept the *timeout*
21 argument; use the :func:`asyncio.wait_for` function to perform
22 operations with timeouts.
23
24 asyncio has the following basic synchronization primitives:
25
26 * :class:`Lock`
27 * :class:`Event`
28 * :class:`Condition`
29 * :class:`Semaphore`
30 * :class:`BoundedSemaphore`
31 * :class:`Barrier`
32
33
34 ---------
35
36
37 Lock
38 ====
39
40 .. class:: Lock()
41
42 Implements a mutex lock for asyncio tasks. Not thread-safe.
43
44 An asyncio lock can be used to guarantee exclusive access to a
45 shared resource.
46
47 The preferred way to use a Lock is an :keyword:`async with`
48 statement::
49
50 lock = asyncio.Lock()
51
52 # ... later
53 async with lock:
54 # access shared state
55
56 which is equivalent to::
57
58 lock = asyncio.Lock()
59
60 # ... later
61 await lock.acquire()
62 try:
63 # access shared state
64 finally:
65 lock.release()
66
67 .. versionchanged:: 3.10
68 Removed the *loop* parameter.
69
70 .. method:: acquire()
71 :async:
72
73 Acquire the lock.
74
75 This method waits until the lock is *unlocked*, sets it to
76 *locked* and returns ``True``.
77
78 When more than one coroutine is blocked in :meth:`acquire`
79 waiting for the lock to be unlocked, only one coroutine
80 eventually proceeds.
81
82 Acquiring a lock is *fair*: the coroutine that proceeds will be
83 the first coroutine that started waiting on the lock.
84
85 .. method:: release()
86
87 Release the lock.
88
89 When the lock is *locked*, reset it to *unlocked* and return.
90
91 If the lock is *unlocked*, a :exc:`RuntimeError` is raised.
92
93 .. method:: locked()
94
95 Return ``True`` if the lock is *locked*.
96
97
98 Event
99 =====
100
101 .. class:: Event()
102
103 An event object. Not thread-safe.
104
105 An asyncio event can be used to notify multiple asyncio tasks
106 that some event has happened.
107
108 An Event object manages an internal flag that can be set to *true*
109 with the :meth:`~Event.set` method and reset to *false* with the
110 :meth:`clear` method. The :meth:`~Event.wait` method blocks until the
111 flag is set to *true*. The flag is set to *false* initially.
112
113 .. versionchanged:: 3.10
114 Removed the *loop* parameter.
115
116 .. _asyncio_example_sync_event:
117
118 Example::
119
120 async def waiter(event):
121 print('waiting for it ...')
122 await event.wait()
123 print('... got it!')
124
125 async def main():
126 # Create an Event object.
127 event = asyncio.Event()
128
129 # Spawn a Task to wait until 'event' is set.
130 waiter_task = asyncio.create_task(waiter(event))
131
132 # Sleep for 1 second and set the event.
133 await asyncio.sleep(1)
134 event.set()
135
136 # Wait until the waiter task is finished.
137 await waiter_task
138
139 asyncio.run(main())
140
141 .. method:: wait()
142 :async:
143
144 Wait until the event is set.
145
146 If the event is set, return ``True`` immediately.
147 Otherwise block until another task calls :meth:`~Event.set`.
148
149 .. method:: set()
150
151 Set the event.
152
153 All tasks waiting for event to be set will be immediately
154 awakened.
155
156 .. method:: clear()
157
158 Clear (unset) the event.
159
160 Subsequent tasks awaiting on :meth:`~Event.wait` will now block until the
161 :meth:`~Event.set` method is called again.
162
163 .. method:: is_set()
164
165 Return ``True`` if the event is set.
166
167
168 Condition
169 =========
170
171 .. class:: Condition(lock=None)
172
173 A Condition object. Not thread-safe.
174
175 An asyncio condition primitive can be used by a task to wait for
176 some event to happen and then get exclusive access to a shared
177 resource.
178
179 In essence, a Condition object combines the functionality
180 of an :class:`Event` and a :class:`Lock`. It is possible to have
181 multiple Condition objects share one Lock, which allows coordinating
182 exclusive access to a shared resource between different tasks
183 interested in particular states of that shared resource.
184
185 The optional *lock* argument must be a :class:`Lock` object or
186 ``None``. In the latter case a new Lock object is created
187 automatically.
188
189 .. versionchanged:: 3.10
190 Removed the *loop* parameter.
191
192 The preferred way to use a Condition is an :keyword:`async with`
193 statement::
194
195 cond = asyncio.Condition()
196
197 # ... later
198 async with cond:
199 await cond.wait()
200
201 which is equivalent to::
202
203 cond = asyncio.Condition()
204
205 # ... later
206 await cond.acquire()
207 try:
208 await cond.wait()
209 finally:
210 cond.release()
211
212 .. method:: acquire()
213 :async:
214
215 Acquire the underlying lock.
216
217 This method waits until the underlying lock is *unlocked*,
218 sets it to *locked* and returns ``True``.
219
220 .. method:: notify(n=1)
221
222 Wake up *n* tasks (1 by default) waiting on this
223 condition. If fewer than *n* tasks are waiting they are all awakened.
224
225 The lock must be acquired before this method is called and
226 released shortly after. If called with an *unlocked* lock
227 a :exc:`RuntimeError` error is raised.
228
229 .. method:: locked()
230
231 Return ``True`` if the underlying lock is acquired.
232
233 .. method:: notify_all()
234
235 Wake up all tasks waiting on this condition.
236
237 This method acts like :meth:`notify`, but wakes up all waiting
238 tasks.
239
240 The lock must be acquired before this method is called and
241 released shortly after. If called with an *unlocked* lock
242 a :exc:`RuntimeError` error is raised.
243
244 .. method:: release()
245
246 Release the underlying lock.
247
248 When invoked on an unlocked lock, a :exc:`RuntimeError` is
249 raised.
250
251 .. method:: wait()
252 :async:
253
254 Wait until notified.
255
256 If the calling task has not acquired the lock when this method is
257 called, a :exc:`RuntimeError` is raised.
258
259 This method releases the underlying lock, and then blocks until
260 it is awakened by a :meth:`notify` or :meth:`notify_all` call.
261 Once awakened, the Condition re-acquires its lock and this method
262 returns ``True``.
263
264 Note that a task *may* return from this call spuriously,
265 which is why the caller should always re-check the state
266 and be prepared to :meth:`~Condition.wait` again. For this reason, you may
267 prefer to use :meth:`~Condition.wait_for` instead.
268
269 .. method:: wait_for(predicate)
270 :async:
271
272 Wait until a predicate becomes *true*.
273
274 The predicate must be a callable which result will be
275 interpreted as a boolean value. The method will repeatedly
276 :meth:`~Condition.wait` until the predicate evaluates to *true*. The final value is the
277 return value.
278
279
280 Semaphore
281 =========
282
283 .. class:: Semaphore(value=1)
284
285 A Semaphore object. Not thread-safe.
286
287 A semaphore manages an internal counter which is decremented by each
288 :meth:`acquire` call and incremented by each :meth:`release` call.
289 The counter can never go below zero; when :meth:`acquire` finds
290 that it is zero, it blocks, waiting until some task calls
291 :meth:`release`.
292
293 The optional *value* argument gives the initial value for the
294 internal counter (``1`` by default). If the given value is
295 less than ``0`` a :exc:`ValueError` is raised.
296
297 .. versionchanged:: 3.10
298 Removed the *loop* parameter.
299
300 The preferred way to use a Semaphore is an :keyword:`async with`
301 statement::
302
303 sem = asyncio.Semaphore(10)
304
305 # ... later
306 async with sem:
307 # work with shared resource
308
309 which is equivalent to::
310
311 sem = asyncio.Semaphore(10)
312
313 # ... later
314 await sem.acquire()
315 try:
316 # work with shared resource
317 finally:
318 sem.release()
319
320 .. method:: acquire()
321 :async:
322
323 Acquire a semaphore.
324
325 If the internal counter is greater than zero, decrement
326 it by one and return ``True`` immediately. If it is zero, wait
327 until a :meth:`release` is called and return ``True``.
328
329 .. method:: locked()
330
331 Returns ``True`` if semaphore can not be acquired immediately.
332
333 .. method:: release()
334
335 Release a semaphore, incrementing the internal counter by one.
336 Can wake up a task waiting to acquire the semaphore.
337
338 Unlike :class:`BoundedSemaphore`, :class:`Semaphore` allows
339 making more ``release()`` calls than ``acquire()`` calls.
340
341
342 BoundedSemaphore
343 ================
344
345 .. class:: BoundedSemaphore(value=1)
346
347 A bounded semaphore object. Not thread-safe.
348
349 Bounded Semaphore is a version of :class:`Semaphore` that raises
350 a :exc:`ValueError` in :meth:`~Semaphore.release` if it
351 increases the internal counter above the initial *value*.
352
353 .. versionchanged:: 3.10
354 Removed the *loop* parameter.
355
356
357 Barrier
358 =======
359
360 .. class:: Barrier(parties)
361
362 A barrier object. Not thread-safe.
363
364 A barrier is a simple synchronization primitive that allows to block until
365 *parties* number of tasks are waiting on it.
366 Tasks can wait on the :meth:`~Barrier.wait` method and would be blocked until
367 the specified number of tasks end up waiting on :meth:`~Barrier.wait`.
368 At that point all of the waiting tasks would unblock simultaneously.
369
370 :keyword:`async with` can be used as an alternative to awaiting on
371 :meth:`~Barrier.wait`.
372
373 The barrier can be reused any number of times.
374
375 .. _asyncio_example_barrier:
376
377 Example::
378
379 async def example_barrier():
380 # barrier with 3 parties
381 b = asyncio.Barrier(3)
382
383 # create 2 new waiting tasks
384 asyncio.create_task(b.wait())
385 asyncio.create_task(b.wait())
386
387 await asyncio.sleep(0)
388 print(b)
389
390 # The third .wait() call passes the barrier
391 await b.wait()
392 print(b)
393 print("barrier passed")
394
395 await asyncio.sleep(0)
396 print(b)
397
398 asyncio.run(example_barrier())
399
400 Result of this example is::
401
402 <asyncio.locks.Barrier object at 0x... [filling, waiters:2/3]>
403 <asyncio.locks.Barrier object at 0x... [draining, waiters:0/3]>
404 barrier passed
405 <asyncio.locks.Barrier object at 0x... [filling, waiters:0/3]>
406
407 .. versionadded:: 3.11
408
409 .. method:: wait()
410 :async:
411
412 Pass the barrier. When all the tasks party to the barrier have called
413 this function, they are all unblocked simultaneously.
414
415 When a waiting or blocked task in the barrier is cancelled,
416 this task exits the barrier which stays in the same state.
417 If the state of the barrier is "filling", the number of waiting task
418 decreases by 1.
419
420 The return value is an integer in the range of 0 to ``parties-1``, different
421 for each task. This can be used to select a task to do some special
422 housekeeping, e.g.::
423
424 ...
425 async with barrier as position:
426 if position == 0:
427 # Only one task prints this
428 print('End of *draining phase*')
429
430 This method may raise a :class:`BrokenBarrierError` exception if the
431 barrier is broken or reset while a task is waiting.
432 It could raise a :exc:`CancelledError` if a task is cancelled.
433
434 .. method:: reset()
435 :async:
436
437 Return the barrier to the default, empty state. Any tasks waiting on it
438 will receive the :class:`BrokenBarrierError` exception.
439
440 If a barrier is broken it may be better to just leave it and create a new one.
441
442 .. method:: abort()
443 :async:
444
445 Put the barrier into a broken state. This causes any active or future
446 calls to :meth:`~Barrier.wait` to fail with the :class:`BrokenBarrierError`.
447 Use this for example if one of the tasks needs to abort, to avoid infinite
448 waiting tasks.
449
450 .. attribute:: parties
451
452 The number of tasks required to pass the barrier.
453
454 .. attribute:: n_waiting
455
456 The number of tasks currently waiting in the barrier while filling.
457
458 .. attribute:: broken
459
460 A boolean that is ``True`` if the barrier is in the broken state.
461
462
463 .. exception:: BrokenBarrierError
464
465 This exception, a subclass of :exc:`RuntimeError`, is raised when the
466 :class:`Barrier` object is reset or broken.
467
468 ---------
469
470
471 .. versionchanged:: 3.9
472
473 Acquiring a lock using ``await lock`` or ``yield from lock`` and/or
474 :keyword:`with` statement (``with await lock``, ``with (yield from
475 lock)``) was removed. Use ``async with lock`` instead.