This library implements a Nursery object, similar to trio's Nursery for
async def child(): ... async def parent(): async with aionursery.Nursery() as nursery: # Make two concurrent calls to child nursery.start_soon(child()) nursery.start_soon(child())
Tasks form a tree: when you run your main coroutine (via
asyncio.run), this creates an initial task, and all your other tasks will be children, grandchildren, etc. of the main task.
The body of the
async with block acts like an initial task that's running inside the nursery, and then each call to
nursery.start_soon adds another task that runs in parallel.
Keep in mind that:
- If any task inside the nursery raises an unhandled exception, then the nursery immediately cancels all the tasks inside the nursery.
- Since all of the tasks are running concurrently inside the async with block, the block does not exit until all tasks have completed. If you’ve used other concurrency frameworks, then you can think of it as, the de-indentation at the end of the async with automatically “joins” (waits for) all of the tasks in the nursery.
- Once all the tasks have finished, then: * The nursery is marked as “closed”, meaning that no new tasks can be started inside it. * Any unhandled exceptions are re-raised inside the parent task. If there are multiple exceptions, then they’re collected up into a single MultiError exception.
Since all tasks are descendents of the initial task, one consequence of this is that the parent can’t finish until all tasks have finished.
Please note that you can't reuse an already exited nursery. Trying to re-open it again, or to
start_soon more tasks in it will raise
Shielding some tasks from being cancelled
Sometimes, however, you need to have an opposite behavior: a child must execute no matter what exceptions are raised in other tasks. Imagine a payment transaction running in one task, and an sms sending in another. You certainly don't want an sms sending error to cancel a payment transaction.
For that, you can
asyncio.shield your tasks before starting them in the nursery:
async def perform_payment(): ... async def send_sms(): ... async def parent(): async with Nursery() as nursery: nursery.start_soon(asyncio.shield(perform_payment())) nursery.start_soon(send_sms())
Getting results from children
If your background tasks are not quite long-lived and return some useful values that you want to process, you can gather all tasks into a list and use
asyncio.wait (or similar functions) as usual:
async def parent(): async with Nursery() as nursery: task_foo = nursery.start_soon(foo()) task_bar = nursery.start_soon(bar()) results = await asyncio.wait([task_foo, task_bar])
If your background tasks are long-lived, you should use
asyncio.Queue to pass objects between children and parent tasks:
async def child(queue): while True: data = await from_external_system() await queue.put(data) async def parent(): queue = asyncio.Queue() async with Nursery() as nursery: nursery.start_soon(child(queue)) while some_condition(): data = await queue.get() await do_stuff_with(data)
You can wrap a nursery in a
async_timeout.timeout context manager.
When timeout happens, the whole nursery cancels:
from async_timeout import timeout async def child(): await asyncio.sleep(1000 * 1000) async def parent(): async with timeout(10): async with Nursery() as nursery: nursery.start_soon(child()) await asyncio.sleep(1000 * 1000)