Crate pyo3_asyncio[−][src]
Rust Bindings to the Python Asyncio Event Loop
Motivation
This crate aims to provide a convenient interface to manage the interop between Python and Rust's async/await models. It supports conversions between Rust and Python futures and manages the event loops for both languages. Python's threading model and GIL can make this interop a bit trickier than one might expect, so there are a few caveats that users should be aware of.
Why Two Event Loops
Currently, we don't have a way to run Rust futures directly on Python's event loop. Likewise, Python's coroutines cannot be directly spawned on a Rust event loop. The two coroutine models require some additional assistance from their event loops, so in all likelihood they will need a new unique event loop that addresses the needs of both languages if the coroutines are to be run on the same loop.
It's not immediately clear that this would provide worthwhile performance wins either, so in the interest of keeping things simple, this crate creates and manages the Python event loop and handles the communication between separate Rust event loops.
Python's Event Loop
Python is very picky about the threads used by the asyncio
executor. In particular, it needs
to have control over the main thread in order to handle signals like CTRL-C correctly. This
means that Cargo's default test harness will no longer work since it doesn't provide a method of
overriding the main function to add our event loop initialization and finalization.
Rust's Event Loop
Currently only the async-std and Tokio runtimes are supported by this crate.
In the future, more runtimes may be supported for Rust.
Features
Items marked with
attributes
are only available when the attributes
Cargo feature is enabled:
[dependencies.pyo3-asyncio]
version = "0.13.0"
features = ["attributes"]
Items marked with
async-std-runtime
are only available when the async-std-runtime
Cargo feature is enabled:
[dependencies.pyo3-asyncio]
version = "0.13.0"
features = ["async-std-runtime"]
Items marked with
tokio-runtime
are only available when the tokio-runtime
Cargo feature is enabled:
[dependencies.pyo3-asyncio]
version = "0.13.0"
features = ["tokio-runtime"]
Items marked with
testing
are only available when the testing
Cargo feature is enabled:
[dependencies.pyo3-asyncio]
version = "0.13.0"
features = ["testing"]
Re-exports
pub use inventory; |
Modules
async_std |
|
generic | Generic implementations of PyO3 Asyncio utilities that can be used for any Rust runtime |
testing |
|
tokio |
|
Functions
get_event_loop | Get a reference to the Python Event Loop from Rust |
into_future | Convert a Python |
run_forever | Run the event loop forever |
with_runtime | Wraps the provided function with the initialization and finalization for PyO3 Asyncio |