Rollup merge of #141867 - Diggsey:db-improve-future-docs, r=tgross35

Describe Future invariants more precisely

1 files changed, 16 insertions, 7 deletions

diff --git a/library/core/src/future/future.rs b/library/core/src/future/future.rs
index cfbd88bbe79..fab13bb7c85 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)`.