diff options
Diffstat (limited to 'src/task/blocking.rs')
| -rw-r--r-- | src/task/blocking.rs | 141 |
1 files changed, 61 insertions, 80 deletions
diff --git a/src/task/blocking.rs b/src/task/blocking.rs index ed60f4c..fc6632b 100644 --- a/src/task/blocking.rs +++ b/src/task/blocking.rs @@ -1,6 +1,6 @@ use crate::task::JoinHandle; -cfg_rt_threaded! { +cfg_rt_multi_thread! { /// Runs the provided blocking function on the current thread without /// blocking the executor. /// @@ -17,7 +17,7 @@ cfg_rt_threaded! { /// using the [`join!`] macro. To avoid this issue, use [`spawn_blocking`] /// instead. /// - /// Note that this function can only be used on the [threaded scheduler]. + /// Note that this function can only be used when using the `multi_thread` runtime. /// /// Code running behind `block_in_place` cannot be cancelled. When you shut /// down the executor, it will wait indefinitely for all blocking operations @@ -27,7 +27,6 @@ cfg_rt_threaded! { /// 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 @@ -44,7 +43,6 @@ cfg_rt_threaded! { /// }); /// # } /// ``` - #[cfg_attr(docsrs, doc(cfg(feature = "blocking")))] pub fn block_in_place<F, R>(f: F) -> R where F: FnOnce() -> R, @@ -53,80 +51,63 @@ cfg_rt_threaded! { } } -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) - } +/// 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 problematic, 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. When running many CPU-bound computations, a +/// semaphore or some other synchronization primitive should be used to limit +/// the number of computation executed in parallel. Specialized CPU-bound +/// executors, such as [rayon], may also be a good fit. +/// +/// 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 single threaded runtime, 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 +/// [`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, +{ + crate::runtime::spawn_blocking(f) } |