18.5.7. Synchronization primitives¶
18.5.7.1. Locks¶
18.5.7.1.1. Lock¶
-
class
asyncio.
Lock
(*, loop=None)¶ Primitive lock objects.
A primitive lock is a synchronization primitive that is not owned by a particular coroutine when locked. A primitive lock is in one of two states, ‘locked’ or ‘unlocked’.
It is created in the unlocked state. It has two basic methods,
acquire()
andrelease()
. When the state is unlocked, acquire() changes the state to locked and returns immediately. When the state is locked, acquire() blocks until a call to release() in another coroutine changes it to unlocked, then the acquire() call resets it to locked and returns. The release() method should only be called in the locked state; it changes the state to unlocked and returns immediately. If an attempt is made to release an unlocked lock, aRuntimeError
will be raised.When more than one coroutine is blocked in acquire() waiting for the state to turn to unlocked, only one coroutine proceeds when a release() call resets the state to unlocked; first coroutine which is blocked in acquire() is being processed.
acquire()
is a coroutine and should be called withyield from
.Locks also support the context management protocol.
(yield from lock)
should be used as context manager expression.Usage:
lock = Lock() ... yield from lock try: ... finally: lock.release()
Context manager usage:
lock = Lock() ... with (yield from lock): ...
Lock objects can be tested for locking state:
if not lock.locked(): yield from lock else: # lock is acquired ...
-
locked
()¶ Return
True
if the lock is acquired.
-
acquire
()¶ Acquire a lock.
This method blocks until the lock is unlocked, then sets it to locked and returns
True
.This method is a coroutine.
-
release
()¶ Release a lock.
When the lock is locked, reset it to unlocked, and return. If any other coroutines are blocked waiting for the lock to become unlocked, allow exactly one of them to proceed.
When invoked on an unlocked lock, a
RuntimeError
is raised.There is no return value.
-
18.5.7.1.2. Event¶
-
class
asyncio.
Event
(*, loop=None)¶ An Event implementation, asynchronous equivalent to
threading.Event
.Class implementing event objects. An event manages a flag that can be set to true with the
set()
method and reset to false with theclear()
method. Thewait()
method blocks until the flag is true. The flag is initially false.-
clear
()¶ Reset the internal flag to false. Subsequently, coroutines calling
wait()
will block untilset()
is called to set the internal flag to true again.
-
is_set
()¶ Return
True
if and only if the internal flag is true.
-
18.5.7.1.3. Condition¶
-
class
asyncio.
Condition
(lock=None, *, loop=None)¶ A Condition implementation, asynchronous equivalent to
threading.Condition
.This class implements condition variable objects. A condition variable allows one or more coroutines to wait until they are notified by another coroutine.
If the lock argument is given and not
None
, it must be aLock
object, and it is used as the underlying lock. Otherwise, a newLock
object is created and used as the underlying lock.-
acquire
()¶ Acquire the underlying lock.
This method blocks until the lock is unlocked, then sets it to locked and returns
True
.This method is a coroutine.
-
notify
(n=1)¶ By default, wake up one coroutine waiting on this condition, if any. If the calling coroutine has not acquired the lock when this method is called, a
RuntimeError
is raised.This method wakes up at most n of the coroutines waiting for the condition variable; it is a no-op if no coroutines are waiting.
-
locked
()¶ Return
True
if the underlying lock is acquired.
-
notify_all
()¶ Wake up all threads waiting on this condition. This method acts like
notify()
, but wakes up all waiting threads instead of one. If the calling thread has not acquired the lock when this method is called, aRuntimeError
is raised.
-
release
()¶ Release the underlying lock.
When the lock is locked, reset it to unlocked, and return. If any other coroutines are blocked waiting for the lock to become unlocked, allow exactly one of them to proceed.
When invoked on an unlocked lock, a
RuntimeError
is raised.There is no return value.
-
wait
()¶ Wait until notified.
If the calling coroutine has not acquired the lock when this method is called, a
RuntimeError
is raised.This method releases the underlying lock, and then blocks until it is awakened by a
notify()
ornotify_all()
call for the same condition variable in another coroutine. Once awakened, it re-acquires the lock and returnsTrue
.This method is a coroutine.
-
18.5.7.2. Semaphores¶
18.5.7.2.1. Semaphore¶
-
class
asyncio.
Semaphore
(value=1, *, loop=None)¶ A Semaphore implementation.
A semaphore manages an internal counter which is decremented by each
acquire()
call and incremented by eachrelease()
call. The counter can never go below zero; whenacquire()
finds that it is zero, it blocks, waiting until some other thread callsrelease()
.Semaphores also support the context management protocol.
The optional argument gives the initial value for the internal counter; it defaults to
1
. If the value given is less than0
,ValueError
is raised.-
acquire
()¶ Acquire a semaphore.
If the internal counter is larger than zero on entry, decrement it by one and return
True
immediately. If it is zero on entry, block, waiting until some other coroutine has calledrelease()
to make it larger than0
, and then returnTrue
.This method is a coroutine.
-
locked
()¶ Returns
True
if semaphore can not be acquired immediately.
-
release
()¶ Release a semaphore, incrementing the internal counter by one. When it was zero on entry and another coroutine is waiting for it to become larger than zero again, wake up that coroutine.
-
18.5.7.2.2. BoundedSemaphore¶
-
class
asyncio.
BoundedSemaphore
(value=1, *, loop=None)¶ A bounded semaphore implementation. Inherit from
Semaphore
.This raises
ValueError
inrelease()
if it would increase the value above the initial value.
18.5.7.3. Queues¶
18.5.7.3.1. Queue¶
-
class
asyncio.
Queue
(maxsize=0, *, loop=None)¶ A queue, useful for coordinating producer and consumer coroutines.
If maxsize is less than or equal to zero, the queue size is infinite. If it is an integer greater than
0
, thenyield from put()
will block when the queue reaches maxsize, until an item is removed byget()
.Unlike the standard library
queue
, you can reliably know this Queue’s size withqsize()
, since your single-threaded asyncio application won’t be interrupted between callingqsize()
and doing an operation on the Queue.-
empty
()¶ Return
True
if the queue is empty,False
otherwise.
-
full
()¶ Return
True
if there are maxsize items in the queue.Note
If the Queue was initialized with
maxsize=0
(the default), thenfull()
is neverTrue
.
-
get
()¶ Remove and return an item from the queue.
If you yield from
get()
, wait until a item is available.This method is a coroutine.
-
get_nowait
()¶ Remove and return an item from the queue.
Return an item if one is immediately available, else raise
QueueEmpty
.
-
put
(item)¶ Put an item into the queue.
If you yield from
put()
, wait until a free slot is available before adding item.This method is a coroutine.
-
put_nowait
(item)¶ Put an item into the queue without blocking.
If no free slot is immediately available, raise
QueueFull
.
-
qsize
()¶ Number of items in the queue.
-
maxsize
¶ Number of items allowed in the queue.
-
18.5.7.3.2. PriorityQueue¶
18.5.7.3.3. LifoQueue¶
18.5.7.3.4. JoinableQueue¶
-
class
asyncio.
JoinableQueue
¶ A subclass of
Queue
withtask_done()
andjoin()
methods.-
join
()¶ Block until all items in the queue have been gotten and processed.
The count of unfinished tasks goes up whenever an item is added to the queue. The count goes down whenever a consumer thread calls
task_done()
to indicate that the item was retrieved and all work on it is complete. When the count of unfinished tasks drops to zero,join()
unblocks.This method is a coroutine.
-
task_done
()¶ Indicate that a formerly enqueued task is complete.
Used by queue consumers. For each
get()
used to fetch a task, a subsequent call totask_done()
tells the queue that the processing on the task is complete.If a
join()
is currently blocking, it will resume when all items have been processed (meaning that atask_done()
call was received for every item that had beenput()
into the queue).Raises
ValueError
if called more times than there were items placed in the queue.
-
18.5.7.3.5. Exceptions¶
-
exception
asyncio.
QueueEmpty
¶ Exception raised when non-blocking
get()
(orget_nowait()
) is called on aQueue
object which is empty.
-
exception
asyncio.
QueueFull
¶ Exception raised when non-blocking
put()
(orput_nowait()
) is called on aQueue
object which is full.