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

macros: render more comprehensible documentation for try_join! (#6841)

Browse Source 
Signed-off-by: Rustin170506 <[email protected]>
This commit is contained in:
Rustin
2024-09-14 11:34:45 +02:00
committed by GitHub
parent a2496548d1
commit 83e922f051
1 changed files with 116 additions and 104 deletions
Download Patch File Download Diff File Expand all files Collapse all files
tokio/src/macros/try_join.rs
+116 -104
View File
@@ -1,106 +1,118 @@
/// Waits on multiple concurrent branches, returning when **all** branches macro_rules! doc {
/// complete with `Ok(_)` or on the first `Err(_)`. ($try_join:item) => {
/// /// Waits on multiple concurrent branches, returning when **all** branches
/// The `try_join!` macro must be used inside of async functions, closures, and /// complete with `Ok(_)` or on the first `Err(_)`.
/// blocks. ///
/// /// The `try_join!` macro must be used inside of async functions, closures, and
/// Similar to [`join!`], the `try_join!` macro takes a list of async /// blocks.
/// expressions and evaluates them concurrently on the same task. Each async ///
/// expression evaluates to a future and the futures from each expression are /// Similar to [`join!`], the `try_join!` macro takes a list of async
/// multiplexed on the current task. The `try_join!` macro returns when **all** /// expressions and evaluates them concurrently on the same task. Each async
/// branches return with `Ok` or when the **first** branch returns with `Err`. /// expression evaluates to a future and the futures from each expression are
/// /// multiplexed on the current task. The `try_join!` macro returns when **all**
/// [`join!`]: macro@join /// branches return with `Ok` or when the **first** branch returns with `Err`.
/// ///
/// # Notes /// [`join!`]: macro@join
/// ///
/// The supplied futures are stored inline and do not require allocating a /// # Notes
/// `Vec`. ///
/// /// The supplied futures are stored inline and do not require allocating a
/// ### Runtime characteristics /// `Vec`.
/// ///
/// By running all async expressions on the current task, the expressions are /// ### Runtime characteristics
/// able to run **concurrently** but not in **parallel**. This means all ///
/// expressions are run on the same thread and if one branch blocks the thread, /// By running all async expressions on the current task, the expressions are
/// all other expressions will be unable to continue. If parallelism is /// able to run **concurrently** but not in **parallel**. This means all
/// required, spawn each async expression using [`tokio::spawn`] and pass the /// expressions are run on the same thread and if one branch blocks the thread,
/// join handle to `try_join!`. /// all other expressions will be unable to continue. If parallelism is
/// /// required, spawn each async expression using [`tokio::spawn`] and pass the
/// [`tokio::spawn`]: crate::spawn /// join handle to `try_join!`.
/// ///
/// # Examples /// [`tokio::spawn`]: crate::spawn
/// ///
/// Basic `try_join` with two branches. /// # Examples
/// ///
/// ``` /// Basic `try_join` with two branches.
/// async fn do_stuff_async() -> Result<(), &'static str> { ///
/// // async work /// ```
/// # Ok(()) /// async fn do_stuff_async() -> Result<(), &'static str> {
/// } /// // async work
/// /// # Ok(())
/// async fn more_async_work() -> Result<(), &'static str> { /// }
/// // more here ///
/// # Ok(()) /// async fn more_async_work() -> Result<(), &'static str> {
/// } /// // more here
/// /// # Ok(())
/// #[tokio::main] /// }
/// async fn main() { ///
/// let res = tokio::try_join!( /// #[tokio::main]
/// do_stuff_async(), /// async fn main() {
/// more_async_work()); /// let res = tokio::try_join!(
/// /// do_stuff_async(),
/// match res { /// more_async_work());
/// Ok((first, second)) => { ///
/// // do something with the values /// match res {
/// } /// Ok((first, second)) => {
/// Err(err) => { /// // do something with the values
/// println!("processing failed; error = {}", err); /// }
/// } /// Err(err) => {
/// } /// println!("processing failed; error = {}", err);
/// } /// }
/// ``` /// }
/// /// }
/// Using `try_join!` with spawned tasks. /// ```
/// ///
/// ``` /// Using `try_join!` with spawned tasks.
/// use tokio::task::JoinHandle; ///
/// /// ```
/// async fn do_stuff_async() -> Result<(), &'static str> { /// use tokio::task::JoinHandle;
/// // async work ///
/// # Err("failed") /// async fn do_stuff_async() -> Result<(), &'static str> {
/// } /// // async work
/// /// # Err("failed")
/// async fn more_async_work() -> Result<(), &'static str> { /// }
/// // more here ///
/// # Ok(()) /// async fn more_async_work() -> Result<(), &'static str> {
/// } /// // more here
/// /// # Ok(())
/// async fn flatten<T>(handle: JoinHandle<Result<T, &'static str>>) -> Result<T, &'static str> { /// }
/// match handle.await { ///
/// Ok(Ok(result)) => Ok(result), /// async fn flatten<T>(handle: JoinHandle<Result<T, &'static str>>) -> Result<T, &'static str> {
/// Ok(Err(err)) => Err(err), /// match handle.await {
/// Err(err) => Err("handling failed"), /// Ok(Ok(result)) => Ok(result),
/// } /// Ok(Err(err)) => Err(err),
/// } /// Err(err) => Err("handling failed"),
/// /// }
/// #[tokio::main] /// }
/// async fn main() { ///
/// let handle1 = tokio::spawn(do_stuff_async()); /// #[tokio::main]
/// let handle2 = tokio::spawn(more_async_work()); /// async fn main() {
/// match tokio::try_join!(flatten(handle1), flatten(handle2)) { /// let handle1 = tokio::spawn(do_stuff_async());
/// Ok(val) => { /// let handle2 = tokio::spawn(more_async_work());
/// // do something with the values /// match tokio::try_join!(flatten(handle1), flatten(handle2)) {
/// } /// Ok(val) => {
/// Err(err) => { /// // do something with the values
/// println!("Failed with {}.", err); /// }
/// # assert_eq!(err, "failed"); /// Err(err) => {
/// } /// println!("Failed with {}.", err);
/// } /// # assert_eq!(err, "failed");
/// } /// }
/// ``` /// }
#[macro_export] /// }
#[cfg_attr(docsrs, doc(cfg(feature = "macros")))] /// ```
macro_rules! try_join { #[macro_export]
#[cfg_attr(docsrs, doc(cfg(feature = "macros")))]
$try_join
};
}
#[cfg(doc)]
doc! {macro_rules! try_join {
($($future:expr),*) => { unimplemented!() }
}}
#[cfg(not(doc))]
doc! {macro_rules! try_join {
(@ { (@ {
// One `_` for each branch in the `try_join!` macro. This is not used once // One `_` for each branch in the `try_join!` macro. This is not used once
// normalization is complete. // normalization is complete.
@@ -215,4 +227,4 @@ macro_rules! try_join {
}; };
() => { async { Ok(()) }.await } () => { async { Ok(()) }.await }
} }}