任务同步和通信¶

Synchronizing and communicating between tasks

中文

Trio 提供了一组标准的同步和任务间通信原语。这些对象的 API 通常是根据标准库中的类似类建模的，但也存在一些差异。

英文

Trio provides a standard set of synchronization and inter-task communication primitives. These objects' APIs are generally modelled off of the analogous classes in the standard library, but with some differences.

阻塞和非阻塞方法¶

Blocking and non-blocking methods

中文

标准库的同步原语提供了多种机制来指定超时和阻塞行为，并且可以指示一个操作是因成功还是因超时返回的。

在 Trio 中，我们统一采用以下约定：

我们不提供超时参数。如果你需要超时，可以使用取消作用域（cancel scope）。
对于具有非阻塞版本的操作，阻塞和非阻塞版本是不同的方法，分别命名为 X 和 X_nowait。（这类似于 queue.Queue，但不同于大多数 threading 中的类。）我们喜欢这种方法，因为它使我们能够将阻塞版本设为异步，而将非阻塞版本设为同步。
当非阻塞方法无法成功执行时（例如通道为空、锁已经被占用等），它会引发 trio.WouldBlock 异常。没有类似于 queue.Empty 和 queue.Full 的区别 —— 我们只使用一个异常，并始终如一地使用它。

英文

The standard library synchronization primitives have a variety of mechanisms for specifying timeouts and blocking behavior, and of signaling whether an operation returned due to success versus a timeout.

In Trio, we standardize on the following conventions:

We don't provide timeout arguments. If you want a timeout, then use
a cancel scope.
For operations that have a non-blocking variant, the blocking and
non-blocking variants are different methods with names like X and X_nowait, respectively. (This is similar to queue.Queue, but unlike most of the classes in threading.) We like this approach because it allows us to make the blocking version async and the non-blocking version sync.
When a non-blocking method cannot succeed (the channel is empty, the
lock is already held, etc.), then it raises trio.WouldBlock. There's no equivalent to the queue.Empty versus queue.Full distinction – we just have the one exception that we use consistently.

公平性¶

Fairness

中文

这些类都保证是“公平的”，这意味着在选择谁将下一个获得锁、从队列中取出项等操作时，任务总是按照等待时间最长的顺序来决定。虽然目前尚不完全清楚这是否是最好的选择（参见 issues#54 ），但目前就是这样工作的。

作为这个含义的一个例子，下面是一个小程序，其中两个任务竞争一个锁。请注意，释放锁的任务总是在其他任务有机会运行之前立即尝试重新获取锁。（请记住，我们这里使用的是协作式多任务，所以实际上是 确定性 的，释放锁的任务会在其他任务醒来之前调用 acquire()；在 Trio 中，释放锁不是一个检查点。）如果使用不公平的锁，这将导致同一个任务永远持有锁，另一个任务被饿死。但如果你运行这个程序，你会看到两个任务轮流获得锁：

# fairness-demo.py

import trio

async def loopy_child(number, lock):
   while True:
      async with lock:
            print(f"Child {number} has the lock!")
            await trio.sleep(0.5)

async def main():
   async with trio.open_nursery() as nursery:
      lock = trio.Lock()
      nursery.start_soon(loopy_child, 1, lock)
      nursery.start_soon(loopy_child, 2, lock)

trio.run(main)

英文

These classes are all guaranteed to be "fair", meaning that when it comes time to choose who will be next to acquire a lock, get an item from a queue, etc., then it always goes to the task which has been waiting longest. It's not entirely clear whether this is the best choice, but for now that's how it works.

As an example of what this means, here's a small program in which two tasks compete for a lock. Notice that the task which releases the lock always immediately attempts to re-acquire it, before the other task has a chance to run. (And remember that we're doing cooperative multi-tasking here, so it's actually deterministic that the task releasing the lock will call acquire() before the other task wakes up; in Trio releasing a lock is not a checkpoint.) With an unfair lock, this would result in the same task holding the lock forever and the other task being starved out. But if you run this, you'll see that the two tasks politely take turns:

# fairness-demo.py

import trio

async def loopy_child(number, lock):
   while True:
      async with lock:
            print(f"Child {number} has the lock!")
            await trio.sleep(0.5)

async def main():
   async with trio.open_nursery() as nursery:
      lock = trio.Lock()
      nursery.start_soon(loopy_child, 1, lock)
      nursery.start_soon(loopy_child, 2, lock)

trio.run(main)

使用 `Event` 广播事件¶

Broadcasting an event with :class:`Event`

class trio.Event¶

基类：object

A waitable boolean value useful for inter-task synchronization, inspired by threading.Event.

An event object has an internal boolean flag, representing whether the event has happened yet. The flag is initially False, and the wait() method waits until the flag is True. If the flag is already True, then wait() returns immediately. (If the event has already happened, there's nothing to wait for.) The set() method sets the flag to True, and wakes up any waiters.

This behavior is useful because it helps avoid race conditions and lost wakeups: it doesn't matter whether set() gets called just before or after wait(). If you want a lower-level wakeup primitive that doesn't have this protection, consider Condition or trio.lowlevel.ParkingLot.

备注

Unlike threading.Event, trio.Event has no ~threading.Event.clear method. In Trio, once an Event has happened, it cannot un-happen. If you need to represent a series of events, consider creating a new Event object for each one (they're cheap!), or other synchronization methods like channels or trio.lowlevel.ParkingLot.

is_set()¶

Return the current value of the internal flag.

返回类型:: bool

set()¶

Set the internal flag value to True, and wake any waiting tasks.

返回类型:: None

statistics()¶

Return an object containing debugging information.

Currently the following fields are defined: :rtype: EventStatistics

tasks_waiting: The number of tasks blocked on this event's wait() method.

await wait()¶

Block until the internal flag value becomes True.

If it's already True, then this method returns immediately.

返回类型:: None

class trio.EventStatistics(tasks_waiting)¶

基类：object

An object containing debugging information.

Currently the following fields are defined:

tasks_waiting: The number of tasks blocked on this event's trio.Event.wait() method.

较低级别的同步原语¶

Lower-level synchronization primitives

中文

就我个人而言，我发现事件和通道通常足够实现我关心的大多数功能，而且它们比本节中讨论的低级原语更易于阅读代码。但如果你需要它们，它们在这里。（如果你发现自己在使用这些原语来实现新的更高级别的同步原语，那么你可能还想查看 trio.lowlevel 中的设施，以便更直接地接触 Trio 的底层同步逻辑。本节中讨论的所有类都是基于 trio.lowlevel 中的公共 API 实现的；它们没有对 Trio 内部的特殊访问权限。）

class trio.CapacityLimiter(total_tokens)¶

基类：AsyncContextManagerMixin

An object for controlling access to a resource with limited capacity.

Sometimes you need to put a limit on how many tasks can do something at the same time. For example, you might want to use some threads to run multiple blocking I/O operations in parallel... but if you use too many threads at once, then your system can become overloaded and it'll actually make things slower. One popular solution is to impose a policy like "run up to 40 threads at the same time, but no more". But how do you implement a policy like this?

That's what CapacityLimiter is for. You can think of a CapacityLimiter object as a sack that starts out holding some fixed number of tokens:

limit = trio.CapacityLimiter(40)

Then tasks can come along and borrow a token out of the sack:

# Borrow a token:
async with limit:
    # We are holding a token!
    await perform_expensive_operation()
# Exiting the 'async with' block puts the token back into the sack

And crucially, if you try to borrow a token but the sack is empty, then you have to wait for another task to finish what it's doing and put its token back first before you can take it and continue.

Another way to think of it: a CapacityLimiter is like a sofa with a fixed number of seats, and if they're all taken then you have to wait for someone to get up before you can sit down.

By default, trio.to_thread.run_sync() uses a CapacityLimiter to limit the number of threads running at once; see trio.to_thread.current_default_thread_limiter for details.

If you're familiar with semaphores, then you can think of this as a restricted semaphore that's specialized for one common use case, with additional error checking. For a more traditional semaphore, see Semaphore.

备注

Don't confuse this with the "leaky bucket" or "token bucket" algorithms used to limit bandwidth usage on networks. The basic idea of using tokens to track a resource limit is similar, but this is a very simple sack where tokens aren't automatically created or destroyed over time; they're just borrowed and then put back.

await acquire()¶

Borrow a token from the sack, blocking if necessary.

抛出:: RuntimeError -- if the current task already holds one of this sack's tokens.
返回类型:: None

acquire_nowait()¶

Borrow a token from the sack, without blocking.

抛出:

WouldBlock -- if no tokens are available.
RuntimeError -- if the current task already holds one of this sack's tokens.

返回类型:

None

await acquire_on_behalf_of(borrower)¶

Borrow a token from the sack on behalf of borrower, blocking if necessary.

参数:: borrower (Task | object) -- A trio.lowlevel.Task or arbitrary opaque object used to record who is borrowing this token; see acquire_on_behalf_of_nowait() for details.
抛出:: RuntimeError -- if borrower task already holds one of this sack's tokens.
返回类型:: None

acquire_on_behalf_of_nowait(borrower)¶

Borrow a token from the sack on behalf of borrower, without blocking.

参数:

borrower (Task | object) -- A trio.lowlevel.Task or arbitrary opaque object used to record who is borrowing this token. This is used by trio.to_thread.run_sync() to allow threads to "hold tokens", with the intention in the future of using it to allow deadlock detection and other useful things

抛出:

WouldBlock -- if no tokens are available.
RuntimeError -- if borrower already holds one of this sack's tokens.

返回类型:

None

property available_tokens: int | float¶: The amount of capacity that's available to use.

property borrowed_tokens: int¶: The amount of capacity that's currently in use.

release()¶

Put a token back into the sack.

抛出:: RuntimeError -- if the current task has not acquired one of this sack's tokens.
返回类型:: None

release_on_behalf_of(borrower)¶

Put a token back into the sack on behalf of borrower.

抛出:: RuntimeError -- if the given borrower has not acquired one of this sack's tokens.
返回类型:: None

statistics()¶

Return an object containing debugging information.

Currently the following fields are defined: :rtype: CapacityLimiterStatistics

borrowed_tokens: The number of tokens currently borrowed from the sack.
total_tokens: The total number of tokens in the sack. Usually this will be larger than borrowed_tokens, but it's possibly for it to be smaller if total_tokens was recently decreased.
borrowers: A list of all tasks or other entities that currently hold a token.
tasks_waiting: The number of tasks blocked on this CapacityLimiter's acquire() or acquire_on_behalf_of() methods.

property total_tokens: int | float¶

The total capacity available.

You can change total_tokens by assigning to this attribute. If you make it larger, then the appropriate number of waiting tasks will be woken immediately to take the new tokens. If you decrease total_tokens below the number of tasks that are currently using the resource, then all current tasks will be allowed to finish as normal, but no new tasks will be allowed in until the total number of tasks drops below the new total_tokens.

class trio.Semaphore(initial_value, *, max_value=None)¶

基类：AsyncContextManagerMixin

A semaphore.

A semaphore holds an integer value, which can be incremented by calling release() and decremented by calling acquire() – but the value is never allowed to drop below zero. If the value is zero, then acquire() will block until someone calls release().

If you're looking for a Semaphore to limit the number of tasks that can access some resource simultaneously, then consider using a CapacityLimiter instead.

This object's interface is similar to, but different from, that of threading.Semaphore.

A Semaphore object can be used as an async context manager; it blocks on entry but not on exit.

参数:

initial_value (int) -- A non-negative integer giving semaphore's initial value.
max_value (int or None) -- If given, makes this a "bounded" semaphore that raises an error if the value is about to exceed the given max_value.

await acquire()¶

Decrement the semaphore value, blocking if necessary to avoid letting it drop below zero.

返回类型:: None

acquire_nowait()¶

Attempt to decrement the semaphore value, without blocking.

抛出:: WouldBlock -- if the value is zero.
返回类型:: None

property max_value: int | None¶: The maximum allowed value. May be None to indicate no limit.

release()¶

Increment the semaphore value, possibly waking a task blocked in acquire().

抛出:: ValueError -- if incrementing the value would cause it to exceed max_value.
返回类型:: None

statistics()¶

Return an object containing debugging information.

Currently the following fields are defined: :rtype: ParkingLotStatistics

tasks_waiting: The number of tasks blocked on this semaphore's acquire() method.

property value: int¶: The current value of the semaphore.

class trio.Lock¶

基类：_LockImpl

A classic mutex.

This is a non-reentrant, single-owner lock. Unlike threading.Lock, only the owner of the lock is allowed to release it.

A Lock object can be used as an async context manager; it blocks on entry but not on exit.

await acquire()¶

Acquire the lock, blocking if necessary.

抛出:: BrokenResourceError -- if the owner of the lock exits without releasing.
返回类型:: None

acquire_nowait()¶

Attempt to acquire the lock, without blocking.

抛出:: WouldBlock -- if the lock is held.
返回类型:: None

locked()¶

Check whether the lock is currently held.

返回:: True if the lock is held, False otherwise.
返回类型:: bool

release()¶

Release the lock.

抛出:: RuntimeError -- if the calling task does not hold the lock.
返回类型:: None

statistics()¶

Return an object containing debugging information.

Currently the following fields are defined: :rtype: LockStatistics

locked: boolean indicating whether the lock is held.
owner: the trio.lowlevel.Task currently holding the lock, or None if the lock is not held.
tasks_waiting: The number of tasks blocked on this lock's acquire() method.

class trio.StrictFIFOLock¶

基类：_LockImpl

A variant of Lock where tasks are guaranteed to acquire the lock in strict first-come-first-served order.

An example of when this is useful is if you're implementing something like trio.SSLStream or an HTTP/2 server using h2, where you have multiple concurrent tasks that are interacting with a shared state machine, and at unpredictable moments the state machine requests that a chunk of data be sent over the network. (For example, when using h2 simply reading incoming data can occasionally create outgoing data to send.) The challenge is to make sure that these chunks are sent in the correct order, without being garbled.

One option would be to use a regular Lock, and wrap it around every interaction with the state machine:

# This approach is sometimes workable but often sub-optimal; see below
async with lock:
    state_machine.do_something()
    if state_machine.has_data_to_send():
        await conn.sendall(state_machine.get_data_to_send())

But this can be problematic. If you're using h2 then usually reading incoming data doesn't create the need to send any data, so we don't want to force every task that tries to read from the network to sit and wait a potentially long time for sendall to finish. And in some situations this could even potentially cause a deadlock, if the remote peer is waiting for you to read some data before it accepts the data you're sending.

StrictFIFOLock provides an alternative. We can rewrite our example like:

# Note: no awaits between when we start using the state machine and
# when we block to take the lock!
state_machine.do_something()
if state_machine.has_data_to_send():
    # Notice that we fetch the data to send out of the state machine
    # *before* sleeping, so that other tasks won't see it.
    chunk = state_machine.get_data_to_send()
    async with strict_fifo_lock:
        await conn.sendall(chunk)

First we do all our interaction with the state machine in a single scheduling quantum (notice there are no awaits in there), so it's automatically atomic with respect to other tasks. And then if and only if we have data to send, we get in line to send it – and StrictFIFOLock guarantees that each task will send its data in the same order that the state machine generated it.

Currently, StrictFIFOLock is identical to Lock, but (a) this may not always be true in the future, especially if Trio ever implements more sophisticated scheduling policies, and (b) the above code is relying on a pretty subtle property of its lock. Using a StrictFIFOLock acts as an executable reminder that you're relying on this property.

class trio.Condition(lock=None)¶

基类：AsyncContextManagerMixin

A classic condition variable, similar to threading.Condition.

A Condition object can be used as an async context manager to acquire the underlying lock; it blocks on entry but not on exit.

参数:: lock (Lock) -- the lock object to use. If given, must be a trio.Lock. If None, a new Lock will be allocated and used.

await acquire()¶

Acquire the underlying lock, blocking if necessary.

抛出:: BrokenResourceError -- if the owner of the underlying lock exits without releasing.
返回类型:: None

acquire_nowait()¶

Attempt to acquire the underlying lock, without blocking.

抛出:: WouldBlock -- if the lock is currently held.
返回类型:: None

locked()¶

Check whether the underlying lock is currently held.

返回:: True if the lock is held, False otherwise.
返回类型:: bool

notify(n=1)¶

Wake one or more tasks that are blocked in wait().

参数:: n (int) -- The number of tasks to wake.
抛出:: RuntimeError -- if the calling task does not hold the lock.
返回类型:: None

notify_all()¶

Wake all tasks that are currently blocked in wait().

抛出:: RuntimeError -- if the calling task does not hold the lock.
返回类型:: None

release()¶

Release the underlying lock.

返回类型:: None

statistics()¶

Return an object containing debugging information.

Currently the following fields are defined: :rtype: ConditionStatistics

tasks_waiting: The number of tasks blocked on this condition's wait() method.
lock_statistics: The result of calling the underlying Locks statistics() method.

await wait()¶

Wait for another task to call notify() or notify_all().

When calling this method, you must hold the lock. It releases the lock while waiting, and then re-acquires it before waking up.

There is a subtlety with how this method interacts with cancellation: when cancelled it will block to re-acquire the lock before raising Cancelled. This may cause cancellation to be less prompt than expected. The advantage is that it makes code like this work:

async with condition:
    await condition.wait()

If we didn't re-acquire the lock before waking up, and wait() were cancelled here, then we'd crash in condition.__aexit__ when we tried to release the lock we no longer held.

抛出:

RuntimeError -- if the calling task does not hold the lock.
BrokenResourceError -- if the owner of the lock exits without releasing, when attempting to re-acquire.

返回类型:

None

这些原语返回可以被检查的统计对象。

class trio.CapacityLimiterStatistics(borrowed_tokens, total_tokens, borrowers, tasks_waiting)¶

基类：object

An object containing debugging information.

Currently the following fields are defined:

borrowed_tokens: The number of tokens currently borrowed from the sack.
total_tokens: The total number of tokens in the sack. Usually this will be larger than borrowed_tokens, but it's possibly for it to be smaller if trio.CapacityLimiter.total_tokens was recently decreased.
borrowers: A list of all tasks or other entities that currently hold a token.
tasks_waiting: The number of tasks blocked on this CapacityLimiter's trio.CapacityLimiter.acquire() or trio.CapacityLimiter.acquire_on_behalf_of() methods.

class trio.LockStatistics(locked, owner, tasks_waiting)¶

基类：object

An object containing debugging information for a Lock.

Currently the following fields are defined:

locked (boolean): indicating whether the lock is held.
owner: the trio.lowlevel.Task currently holding the lock, or None if the lock is not held.
tasks_waiting (int): The number of tasks blocked on this lock's trio.Lock.acquire() method.

class trio.ConditionStatistics(tasks_waiting, lock_statistics)¶

基类：object

An object containing debugging information for a Condition.

Currently the following fields are defined:

tasks_waiting (int): The number of tasks blocked on this condition's trio.Condition.wait() method.
lock_statistics: The result of calling the underlying Locks statistics() method.

英文

Personally, I find that events and channels are usually enough to implement most things I care about, and lead to easier to read code than the lower-level primitives discussed in this section. But if you need them, they're here. (If you find yourself reaching for these because you're trying to implement a new higher-level synchronization primitive, then you might also want to check out the facilities in trio.lowlevel for a more direct exposure of Trio's underlying synchronization logic. All of classes discussed in this section are implemented on top of the public APIs in trio.lowlevel; they don't have any special access to Trio's internals.)

class trio.CapacityLimiter(total_tokens)

基类：AsyncContextManagerMixin

An object for controlling access to a resource with limited capacity.

That's what CapacityLimiter is for. You can think of a CapacityLimiter object as a sack that starts out holding some fixed number of tokens:

limit = trio.CapacityLimiter(40)

Then tasks can come along and borrow a token out of the sack:

# Borrow a token:
async with limit:
    # We are holding a token!
    await perform_expensive_operation()
# Exiting the 'async with' block puts the token back into the sack

And crucially, if you try to borrow a token but the sack is empty, then you have to wait for another task to finish what it's doing and put its token back first before you can take it and continue.

Another way to think of it: a CapacityLimiter is like a sofa with a fixed number of seats, and if they're all taken then you have to wait for someone to get up before you can sit down.

By default, trio.to_thread.run_sync() uses a CapacityLimiter to limit the number of threads running at once; see trio.to_thread.current_default_thread_limiter for details.

备注

await acquire()

Borrow a token from the sack, blocking if necessary.

抛出:: RuntimeError -- if the current task already holds one of this sack's tokens.
返回类型:: None

acquire_nowait()

Borrow a token from the sack, without blocking.

抛出:

WouldBlock -- if no tokens are available.
RuntimeError -- if the current task already holds one of this sack's tokens.

返回类型:

None

await acquire_on_behalf_of(borrower)

Borrow a token from the sack on behalf of borrower, blocking if necessary.

参数:: borrower (Task | object) -- A trio.lowlevel.Task or arbitrary opaque object used to record who is borrowing this token; see acquire_on_behalf_of_nowait() for details.
抛出:: RuntimeError -- if borrower task already holds one of this sack's tokens.
返回类型:: None

acquire_on_behalf_of_nowait(borrower)

Borrow a token from the sack on behalf of borrower, without blocking.

参数:

borrower (Task | object) -- A trio.lowlevel.Task or arbitrary opaque object used to record who is borrowing this token. This is used by trio.to_thread.run_sync() to allow threads to "hold tokens", with the intention in the future of using it to allow deadlock detection and other useful things

抛出:

WouldBlock -- if no tokens are available.
RuntimeError -- if borrower already holds one of this sack's tokens.

返回类型:

None

property available_tokens: int | float: The amount of capacity that's available to use.

property borrowed_tokens: int: The amount of capacity that's currently in use.

release()

Put a token back into the sack.

抛出:: RuntimeError -- if the current task has not acquired one of this sack's tokens.
返回类型:: None

release_on_behalf_of(borrower)

Put a token back into the sack on behalf of borrower.

抛出:: RuntimeError -- if the given borrower has not acquired one of this sack's tokens.
返回类型:: None

statistics()

Return an object containing debugging information.

Currently the following fields are defined: :rtype: CapacityLimiterStatistics

borrowed_tokens: The number of tokens currently borrowed from the sack.
total_tokens: The total number of tokens in the sack. Usually this will be larger than borrowed_tokens, but it's possibly for it to be smaller if total_tokens was recently decreased.
borrowers: A list of all tasks or other entities that currently hold a token.
tasks_waiting: The number of tasks blocked on this CapacityLimiter's acquire() or acquire_on_behalf_of() methods.

property total_tokens: int | float

The total capacity available.

class trio.Semaphore(initial_value, *, max_value=None)

基类：AsyncContextManagerMixin

A semaphore.

If you're looking for a Semaphore to limit the number of tasks that can access some resource simultaneously, then consider using a CapacityLimiter instead.

This object's interface is similar to, but different from, that of threading.Semaphore.

A Semaphore object can be used as an async context manager; it blocks on entry but not on exit.

参数:

initial_value (int) -- A non-negative integer giving semaphore's initial value.
max_value (int or None) -- If given, makes this a "bounded" semaphore that raises an error if the value is about to exceed the given max_value.

await acquire()

Decrement the semaphore value, blocking if necessary to avoid letting it drop below zero.

返回类型:: None

acquire_nowait()

Attempt to decrement the semaphore value, without blocking.

抛出:: WouldBlock -- if the value is zero.
返回类型:: None

property max_value: int | None: The maximum allowed value. May be None to indicate no limit.

release()

Increment the semaphore value, possibly waking a task blocked in acquire().

抛出:: ValueError -- if incrementing the value would cause it to exceed max_value.
返回类型:: None

statistics()

Return an object containing debugging information.

Currently the following fields are defined: :rtype: ParkingLotStatistics

tasks_waiting: The number of tasks blocked on this semaphore's acquire() method.

property value: int: The current value of the semaphore.

class trio.Lock

基类：_LockImpl

A classic mutex.

This is a non-reentrant, single-owner lock. Unlike threading.Lock, only the owner of the lock is allowed to release it.

A Lock object can be used as an async context manager; it blocks on entry but not on exit.

await acquire()

Acquire the lock, blocking if necessary.

抛出:: BrokenResourceError -- if the owner of the lock exits without releasing.
返回类型:: None

acquire_nowait()

Attempt to acquire the lock, without blocking.

抛出:: WouldBlock -- if the lock is held.
返回类型:: None

locked()

Check whether the lock is currently held.

返回:: True if the lock is held, False otherwise.
返回类型:: bool

release()

Release the lock.

抛出:: RuntimeError -- if the calling task does not hold the lock.
返回类型:: None

statistics()

Return an object containing debugging information.

Currently the following fields are defined: :rtype: LockStatistics

locked: boolean indicating whether the lock is held.
owner: the trio.lowlevel.Task currently holding the lock, or None if the lock is not held.
tasks_waiting: The number of tasks blocked on this lock's acquire() method.

class trio.StrictFIFOLock

基类：_LockImpl

A variant of Lock where tasks are guaranteed to acquire the lock in strict first-come-first-served order.

One option would be to use a regular Lock, and wrap it around every interaction with the state machine:

# This approach is sometimes workable but often sub-optimal; see below
async with lock:
    state_machine.do_something()
    if state_machine.has_data_to_send():
        await conn.sendall(state_machine.get_data_to_send())

StrictFIFOLock provides an alternative. We can rewrite our example like:

# Note: no awaits between when we start using the state machine and
# when we block to take the lock!
state_machine.do_something()
if state_machine.has_data_to_send():
    # Notice that we fetch the data to send out of the state machine
    # *before* sleeping, so that other tasks won't see it.
    chunk = state_machine.get_data_to_send()
    async with strict_fifo_lock:
        await conn.sendall(chunk)

class trio.Condition(lock=None)

基类：AsyncContextManagerMixin

A classic condition variable, similar to threading.Condition.

A Condition object can be used as an async context manager to acquire the underlying lock; it blocks on entry but not on exit.

参数:: lock (Lock) -- the lock object to use. If given, must be a trio.Lock. If None, a new Lock will be allocated and used.

await acquire()

Acquire the underlying lock, blocking if necessary.

抛出:: BrokenResourceError -- if the owner of the underlying lock exits without releasing.
返回类型:: None

acquire_nowait()

Attempt to acquire the underlying lock, without blocking.

抛出:: WouldBlock -- if the lock is currently held.
返回类型:: None

locked()

Check whether the underlying lock is currently held.

返回:: True if the lock is held, False otherwise.
返回类型:: bool

notify(n=1)

Wake one or more tasks that are blocked in wait().

参数:: n (int) -- The number of tasks to wake.
抛出:: RuntimeError -- if the calling task does not hold the lock.
返回类型:: None

notify_all()

Wake all tasks that are currently blocked in wait().

抛出:: RuntimeError -- if the calling task does not hold the lock.
返回类型:: None

release()

Release the underlying lock.

返回类型:: None

statistics()

Return an object containing debugging information.

Currently the following fields are defined: :rtype: ConditionStatistics

tasks_waiting: The number of tasks blocked on this condition's wait() method.
lock_statistics: The result of calling the underlying Locks statistics() method.

await wait()

Wait for another task to call notify() or notify_all().

When calling this method, you must hold the lock. It releases the lock while waiting, and then re-acquires it before waking up.

async with condition:
    await condition.wait()

If we didn't re-acquire the lock before waking up, and wait() were cancelled here, then we'd crash in condition.__aexit__ when we tried to release the lock we no longer held.

抛出:

RuntimeError -- if the calling task does not hold the lock.
BrokenResourceError -- if the owner of the lock exits without releasing, when attempting to re-acquire.

返回类型:

None

These primitives return statistics objects that can be inspected.

class trio.CapacityLimiterStatistics(borrowed_tokens, total_tokens, borrowers, tasks_waiting)

基类：object

An object containing debugging information.

Currently the following fields are defined:

borrowed_tokens: The number of tokens currently borrowed from the sack.
total_tokens: The total number of tokens in the sack. Usually this will be larger than borrowed_tokens, but it's possibly for it to be smaller if trio.CapacityLimiter.total_tokens was recently decreased.
borrowers: A list of all tasks or other entities that currently hold a token.
tasks_waiting: The number of tasks blocked on this CapacityLimiter's trio.CapacityLimiter.acquire() or trio.CapacityLimiter.acquire_on_behalf_of() methods.

class trio.LockStatistics(locked, owner, tasks_waiting)

基类：object

An object containing debugging information for a Lock.

Currently the following fields are defined:

locked (boolean): indicating whether the lock is held.
owner: the trio.lowlevel.Task currently holding the lock, or None if the lock is not held.
tasks_waiting (int): The number of tasks blocked on this lock's trio.Lock.acquire() method.

class trio.ConditionStatistics(tasks_waiting, lock_statistics)

基类：object

An object containing debugging information for a Condition.

Currently the following fields are defined:

tasks_waiting (int): The number of tasks blocked on this condition's trio.Condition.wait() method.
lock_statistics: The result of calling the underlying Locks statistics() method.

任务同步和通信¶

阻塞和非阻塞方法¶

公平性¶

使用 `Event` 广播事件¶

使用通道在任务之间传递值¶

一个简单的通道示例¶

使用通道进行干净关闭¶

管理多个生产者和/或多个消费者¶

在通道中缓冲¶

较低级别的同步原语¶

任务同步和通信¶

阻塞和非阻塞方法¶

公平性¶

使用 Event 广播事件¶

使用通道在任务之间传递值¶

一个简单的通道示例¶

使用通道进行干净关闭¶

管理多个生产者和/或多个消费者¶

在通道中缓冲¶

较低级别的同步原语¶

使用 `Event` 广播事件¶