1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163
//! Tokio context aware futures utilities. //! //! This crate includes utilities around integrating Tokio with other runtimes //! by allowing the context to be attached to futures. This allows spawning //! futures on other executors while still using Tokio to drive them. This //! can be useful if you need to use a Tokio based library in an executor/runtime //! that does not provide a Tokio context. //! //! Be aware that the `.compat()` region allows you to use _both_ Tokio 0.2 and 1 //! features. It is _not_ the case that you opt-out of Tokio 1 when you are inside //! a Tokio 0.2 compatibility region. //! //! Basic usage: //! ``` //! use hyper::{Client, Uri}; //! use tokio_compat_02::FutureExt; //! //! #[tokio::main] //! async fn main() -> Result<(), Box<dyn std::error::Error>> { //! let client = Client::new(); //! //! // This will not panic because we are wrapping it in the //! // Tokio 0.2 context via the `FutureExt::compat` fn. //! client //! .get(Uri::from_static("http://tokio.rs")) //! .compat() //! .await?; //! //! Ok(()) //! } //! ``` //! Usage on async function: //! ``` //! use hyper::{Client, Uri}; //! use tokio_compat_02::FutureExt; //! //! #[tokio::main] //! async fn main() -> Result<(), Box<dyn std::error::Error>> { //! // By calling compat on the async function, everything inside it is able //! // to use Tokio 0.2 features. //! hyper_get().compat().await?; //! Ok(()) //! } //! //! async fn hyper_get() -> Result<(), Box<dyn std::error::Error>> { //! let client = Client::new(); //! //! // This will not panic because the `main` function wrapped it in the //! // Tokio 0.2 context. //! client //! .get(Uri::from_static("http://tokio.rs")) //! .await?; //! //! Ok(()) //! } //! ``` //! Be aware that the constructors of some type require being inside the context. For //! example, this includes `TcpStream` and `delay_for`. //! ``` //! use tokio_02::time::delay_for; //! use tokio_compat_02::FutureExt; //! //! #[tokio::main] //! async fn main() -> Result<(), Box<dyn std::error::Error>> { //! let duration = std::time::Duration::from_secs(1); //! //! // Call the non-async constructor in the context. //! let time_future = async { delay_for(duration) }.compat().await; //! //! // Use the constructed `Delay`. //! time_future.compat().await; //! //! Ok(()) //! } //! ``` //! Of course the above would also work if the surrounding async function was called //! with `.compat()`. #![doc(html_root_url = "https://docs.rs/tokio-compat-02/0.2.0")] use once_cell::sync::OnceCell; use pin_project_lite::pin_project; use std::{ future::Future, pin::Pin, task::{Context, Poll}, }; use tokio_02::runtime::{Handle, Runtime}; mod io; pub use self::io::IoCompat; fn get_handle() -> Handle { static RT: OnceCell<Runtime> = OnceCell::new(); RT.get_or_init(|| { tokio_02::runtime::Builder::new() .threaded_scheduler() .core_threads(1) .enable_all() .build() .unwrap() }) .handle() .clone() } pin_project! { /// `TokioContext` allows connecting a custom executor with the tokio runtime. /// /// It contains a `Handle` to the runtime. A handle to the runtime can be /// obtain by calling the `Runtime::handle()` method. pub struct TokioContext<F> { #[pin] inner: F, handle: Handle, } } impl<F: Future> Future for TokioContext<F> { type Output = F::Output; fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> { let me = self.project(); let handle = me.handle; let fut = me.inner; handle.enter(|| fut.poll(cx)) } } /// Trait extension that simplifies bundling a `Handle` with a `Future`. pub trait FutureExt: Future { /// Compat any future into a future that can run within the Tokio 0.2 /// context. /// /// This will spawn single threaded scheduler in the background globally /// to allow you to call this extension trait method from anywhere. The /// background scheduler supports running Tokio 0.2 futures in any context /// with a small footprint. /// /// # Example /// /// ```rust /// # async fn my_future() {} /// # async fn foo() { /// use tokio_compat_02::FutureExt as _; /// /// my_future().compat().await; /// # } fn compat(self) -> TokioContext<Self> where Self: Sized; } impl<F: Future> FutureExt for F { fn compat(self) -> TokioContext<Self> { TokioContext { inner: self, handle: get_handle(), } } }