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
use crate::task::JoinHandle; cfg_rt_threaded! { /// Runs the provided blocking function on the current thread without /// blocking the executor. /// /// In general, issuing a blocking call or performing a lot of compute in a /// future without yielding is not okay, as it may prevent the executor from /// driving other futures forward. This function runs the closure on the /// current thread by having the thread temporarily cease from being a core /// thread, and turns it into a blocking thread. See the [CPU-bound tasks /// and blocking code][blocking] section for more information. /// /// Although this function avoids starving other independently spawned /// tasks, any other code running concurrently in the same task will be /// suspended during the call to `block_in_place`. This can happen e.g. when /// using the [`join!`] macro. To avoid this issue, use [`spawn_blocking`] /// instead. /// /// Note that this function can only be used on the [threaded scheduler]. /// /// Code running behind `block_in_place` cannot be cancelled. When you shut /// down the executor, it will wait indefinitely for all blocking operations /// to finish. You can use [`shutdown_timeout`] to stop waiting for them /// after a certain timeout. Be aware that this will still not cancel the /// tasks — they are simply allowed to keep running after the method /// returns. /// /// [blocking]: ../index.html#cpu-bound-tasks-and-blocking-code /// [threaded scheduler]: fn@crate::runtime::Builder::threaded_scheduler /// [`spawn_blocking`]: fn@crate::task::spawn_blocking /// [`join!`]: macro@join /// [`thread::spawn`]: fn@std::thread::spawn /// [`shutdown_timeout`]: fn@crate::runtime::Runtime::shutdown_timeout /// /// # Examples /// /// ``` /// use tokio::task; /// /// # async fn docs() { /// task::block_in_place(move || { /// // do some compute-heavy work or call synchronous code /// }); /// # } /// ``` #[cfg_attr(docsrs, doc(cfg(feature = "blocking")))] pub fn block_in_place<F, R>(f: F) -> R where F: FnOnce() -> R, { crate::runtime::thread_pool::block_in_place(f) } } cfg_blocking! { /// Runs the provided closure on a thread where blocking is acceptable. /// /// In general, issuing a blocking call or performing a lot of compute in a /// future without yielding is not okay, as it may prevent the executor from /// driving other futures forward. This function runs the provided closure /// on a thread dedicated to blocking operations. See the [CPU-bound tasks /// and blocking code][blocking] section for more information. /// /// Tokio will spawn more blocking threads when they are requested through /// this function until the upper limit configured on the [`Builder`] is /// reached. This limit is very large by default, because `spawn_blocking` is /// often used for various kinds of IO operations that cannot be performed /// asynchronously. When you run CPU-bound code using `spawn_blocking`, you /// should keep this large upper limit in mind; to run your CPU-bound /// computations on only a few threads, you should use a separate thread /// pool such as [rayon] rather than configuring the number of blocking /// threads. /// /// This function is intended for non-async operations that eventually /// finish on their own. If you want to spawn an ordinary thread, you should /// use [`thread::spawn`] instead. /// /// Closures spawned using `spawn_blocking` cannot be cancelled. When you /// shut down the executor, it will wait indefinitely for all blocking /// operations to finish. You can use [`shutdown_timeout`] to stop waiting /// for them after a certain timeout. Be aware that this will still not /// cancel the tasks — they are simply allowed to keep running after the /// method returns. /// /// Note that if you are using the [basic scheduler], this function will /// still spawn additional threads for blocking operations. The basic /// scheduler's single thread is only used for asynchronous code. /// /// [`Builder`]: struct@crate::runtime::Builder /// [blocking]: ../index.html#cpu-bound-tasks-and-blocking-code /// [rayon]: https://docs.rs/rayon /// [basic scheduler]: fn@crate::runtime::Builder::basic_scheduler /// [`thread::spawn`]: fn@std::thread::spawn /// [`shutdown_timeout`]: fn@crate::runtime::Runtime::shutdown_timeout /// /// # Examples /// /// ``` /// use tokio::task; /// /// # async fn docs() -> Result<(), Box<dyn std::error::Error>>{ /// let res = task::spawn_blocking(move || { /// // do some compute-heavy work or call synchronous code /// "done computing" /// }).await?; /// /// assert_eq!(res, "done computing"); /// # Ok(()) /// # } /// ``` pub fn spawn_blocking<F, R>(f: F) -> JoinHandle<R> where F: FnOnce() -> R + Send + 'static, R: Send + 'static, { #[cfg(feature = "tracing")] let f = { let span = tracing::trace_span!( target: "tokio::task", "task", kind = %"blocking", function = %std::any::type_name::<F>(), ); move || { let _g = span.enter(); f() } }; crate::runtime::spawn_blocking(f) } }