tokio-rs/tokio
1
0
Fork 0
mirror of https://github.com/tokio-rs/tokio.git synced 2026-08-29 00:00:11 +02:00
Code Issues Packages Projects Releases Wiki Activity

task: add missing feature flags for task_local and spawn_blocking (#3237)

Browse Source
This commit is contained in:
Nylonicious
2020-12-09 23:49:28 +01:00
committed by GitHub
parent 473ddaa277
commit 52cd240053
2 changed files with 64 additions and 60 deletions
Download Patch File Download Diff File Expand all files Collapse all files
tokio/src/task/blocking.rs
+62 -60
View File
@@ -51,64 +51,66 @@ cfg_rt_multi_thread! {
} }
} }
/// Runs the provided closure on a thread where blocking is acceptable. cfg_rt! {
/// /// 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 /// In general, issuing a blocking call or performing a lot of compute in a
/// driving other futures forward. This function runs the provided closure on a /// future without yielding is problematic, as it may prevent the executor from
/// thread dedicated to blocking operations. See the [CPU-bound tasks and /// driving other futures forward. This function runs the provided closure on a
/// blocking code][blocking] section for more information. /// 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. /// Tokio will spawn more blocking threads when they are requested through this
/// This limit is very large by default, because `spawn_blocking` is often used /// function until the upper limit configured on the [`Builder`] is reached.
/// for various kinds of IO operations that cannot be performed asynchronously. /// This limit is very large by default, because `spawn_blocking` is often used
/// When you run CPU-bound code using `spawn_blocking`, you should keep this /// for various kinds of IO operations that cannot be performed asynchronously.
/// large upper limit in mind. When running many CPU-bound computations, a /// When you run CPU-bound code using `spawn_blocking`, you should keep this
/// semaphore or some other synchronization primitive should be used to limit /// large upper limit in mind. When running many CPU-bound computations, a
/// the number of computation executed in parallel. Specialized CPU-bound /// semaphore or some other synchronization primitive should be used to limit
/// executors, such as [rayon], may also be a good fit. /// 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 /// This function is intended for non-async operations that eventually finish on
/// [`thread::spawn`] instead. /// 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 /// Closures spawned using `spawn_blocking` cannot be cancelled. When you shut
/// finish. You can use [`shutdown_timeout`] to stop waiting for them after a /// down the executor, it will wait indefinitely for all blocking operations to
/// certain timeout. Be aware that this will still not cancel the tasks — they /// finish. You can use [`shutdown_timeout`] to stop waiting for them after a
/// are simply allowed to keep running after the method returns. /// 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 /// Note that if you are using the single threaded runtime, this function will
/// scheduler's single thread is only used for asynchronous code. /// 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 /// [`Builder`]: struct@crate::runtime::Builder
/// [rayon]: https://docs.rs/rayon /// [blocking]: ../index.html#cpu-bound-tasks-and-blocking-code
/// [`thread::spawn`]: fn@std::thread::spawn /// [rayon]: https://docs.rs/rayon
/// [`shutdown_timeout`]: fn@crate::runtime::Runtime::shutdown_timeout /// [`thread::spawn`]: fn@std::thread::spawn
/// /// [`shutdown_timeout`]: fn@crate::runtime::Runtime::shutdown_timeout
/// # Examples ///
/// /// # Examples
/// ``` ///
/// use tokio::task; /// ```
/// /// use tokio::task;
/// # async fn docs() -> Result<(), Box<dyn std::error::Error>>{ ///
/// let res = task::spawn_blocking(move || { /// # async fn docs() -> Result<(), Box<dyn std::error::Error>>{
/// // do some compute-heavy work or call synchronous code /// let res = task::spawn_blocking(move || {
/// "done computing" /// // do some compute-heavy work or call synchronous code
/// }).await?; /// "done computing"
/// /// }).await?;
/// assert_eq!(res, "done computing"); ///
/// # Ok(()) /// assert_eq!(res, "done computing");
/// # } /// # Ok(())
/// ``` /// # }
#[cfg_attr(tokio_track_caller, track_caller)] /// ```
pub fn spawn_blocking<F, R>(f: F) -> JoinHandle<R> #[cfg_attr(tokio_track_caller, track_caller)]
where pub fn spawn_blocking<F, R>(f: F) -> JoinHandle<R>
F: FnOnce() -> R + Send + 'static, where
R: Send + 'static, F: FnOnce() -> R + Send + 'static,
{ R: Send + 'static,
crate::runtime::spawn_blocking(f) {
crate::runtime::spawn_blocking(f)
}
} }
tokio/src/task/task_local.rs
+2
View File
@@ -31,6 +31,7 @@ use std::{fmt, thread};
/// ///
/// [`tokio::task::LocalKey`]: struct@crate::task::LocalKey /// [`tokio::task::LocalKey`]: struct@crate::task::LocalKey
#[macro_export] #[macro_export]
#[cfg_attr(docsrs, doc(cfg(feature = "rt")))]
macro_rules! task_local { macro_rules! task_local {
// empty (base case for the recursion) // empty (base case for the recursion)
() => {}; () => {};
@@ -90,6 +91,7 @@ macro_rules! __task_local_inner {
/// # } /// # }
/// ``` /// ```
/// [`std::thread::LocalKey`]: struct@std::thread::LocalKey /// [`std::thread::LocalKey`]: struct@std::thread::LocalKey
#[cfg_attr(docsrs, doc(cfg(feature = "rt")))]
pub struct LocalKey<T: 'static> { pub struct LocalKey<T: 'static> {
#[doc(hidden)] #[doc(hidden)]
pub inner: thread::LocalKey<RefCell<Option<T>>>, pub inner: thread::LocalKey<RefCell<Option<T>>>,