diff options
Diffstat (limited to 'tokio/src/task/blocking.rs')
| -rw-r--r-- | tokio/src/task/blocking.rs | 153 |
1 files changed, 74 insertions, 79 deletions
diff --git a/tokio/src/task/blocking.rs b/tokio/src/task/blocking.rs index ed60f4c4..5f9d8af7 100644 --- a/tokio/src/task/blocking.rs +++ b/tokio/src/task/blocking.rs @@ -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,77 @@ 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 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 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, +{ + #[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) } |