diff --git a/library/core/src/future/future.rs b/library/core/src/future/future.rs index cfbd88bbe7998..fab13bb7c8535 100644 --- a/library/core/src/future/future.rs +++ b/library/core/src/future/future.rs @@ -4,7 +4,8 @@ use crate::ops; use crate::pin::Pin; use crate::task::{Context, Poll}; -/// A future represents an asynchronous computation obtained by use of [`async`]. +/// A future represents an asynchronous computation, commonly obtained by use of +/// [`async`]. /// /// A future is a value that might not have finished computing yet. This kind of /// "asynchronous value" makes it possible for a thread to continue doing useful @@ -68,13 +69,21 @@ pub trait Future { /// /// # Runtime characteristics /// - /// Futures alone are *inert*; they must be *actively* `poll`ed to make - /// progress, meaning that each time the current task is woken up, it should - /// actively re-`poll` pending futures that it still has an interest in. + /// Futures alone are *inert*; they must be *actively* `poll`ed for the + /// underlying computation to make progress, meaning that each time the + /// current task is woken up, it should actively re-`poll` pending futures + /// that it still has an interest in. /// - /// The `poll` function is not called repeatedly in a tight loop -- instead, - /// it should only be called when the future indicates that it is ready to - /// make progress (by calling `wake()`). If you're familiar with the + /// Having said that, some Futures may represent a value that is being + /// computed in a different task. In this case, the future's underlying + /// computation is simply acting as a conduit for a value being computed + /// by that other task, which will proceed independently of the Future. + /// Futures of this kind are typically obtained when spawning a new task into an + /// async runtime. + /// + /// The `poll` function should not be called repeatedly in a tight loop -- + /// instead, it should only be called when the future indicates that it is + /// ready to make progress (by calling `wake()`). If you're familiar with the /// `poll(2)` or `select(2)` syscalls on Unix it's worth noting that futures /// typically do *not* suffer the same problems of "all wakeups must poll /// all events"; they are more like `epoll(4)`.