Add some async/await/StableFuture-related docs

Author: cramertj

futures-stable/src/executor.rs

@@ -7,7 +7,11 @@ use futures_executor::{ThreadPool, LocalPool, LocalExecutor};
 use StableFuture;
 use UnsafePin;
 
+/// Executors which can spawn `PinBox`ed futures.
+///
+/// These executors can be used in combination with `StableFuture`s.
 pub trait StableExecutor: Executor {
+    /// Spawn a `PinBox` future.
     fn spawn_pinned(&mut self, f: PinBox<Future<Item = (), Error = Never> + Send>) -> Result<(), SpawnError>;
 }
 
@@ -23,6 +27,7 @@ impl StableExecutor for LocalExecutor {
     }
 }
 
+/// Block on the result of a `StableFuture`.
 pub fn block_on_stable<F: StableFuture>(f: F) -> Result<F::Item, F::Error> {
     let mut pool = LocalPool::new();
     let mut exec = pool.executor();

futures-stable/src/lib.rs

@@ -35,19 +35,44 @@ if_nightly! {
         use unsafe_pin::UnsafePin;
     }
 
+    /// A trait for `Future`s which can be pinned to a particular location in memory.
+    ///
+    /// These futures take `self` by `Pin<Self>`, rather than `&mut Self`.
+    /// This allows types which are not [`Unpin`](::std::marker::Unpin) to guarantee
+    /// that they won't be moved after being polled. Since they won't be moved, it's
+    /// possible for them to safely contain references to themselves.
+    ///
+    /// The most common examples of such self-referential `StableFuture`s are `#[async]`
+    /// functions and `async_block!`s.
+    ///
+    /// All types which implement `Future` also implement `StableFuture` automatically.
     pub trait StableFuture {
+        /// A successful value
         type Item;
+
+        /// An error
         type Error;
 
+        /// Attempt to resolve the future to a final value, registering the current task
+        /// for wakeup if the value is not yet available.
+        ///
+        /// This method takes `self` by `Pin`, and so calling it requires putting `Self`
+        /// in a [`PinBox`](::std::boxed::PinBox) using the `pin` method, or otherwise
+        /// guaranteeing that the location of `self` will not change after a call to `poll`.
         fn poll(self: Pin<Self>, ctx: &mut task::Context) -> Poll<Self::Item, Self::Error>;
 
+        /// Pin the future to a particular location by placing it on the heap.
         #[cfg(feature = "std")]
         fn pin<'a>(self) -> PinBox<Future<Item = Self::Item, Error = Self::Error> + Send + 'a>
             where Self: Send + Sized + 'a
         {
             PinBox::new(unsafe { UnsafePin::new(self) })
         }
 
+        /// Pin the future to a particular location by placing it on the heap.
+        ///
+        /// This method is the same as `pin`, but doesn't require that `Self` can be
+        /// safely sent across threads. `pin` should be preferred where possible.
         #[cfg(feature = "std")]
         fn pin_local<'a>(self) -> PinBox<Future<Item = Self::Item, Error = Self::Error> + 'a>
             where Self: Sized + 'a
@@ -65,19 +90,43 @@ if_nightly! {
         }
     }
 
+    /// A trait for `Stream`s which can be pinned to a particular location in memory.
+    ///
+    /// These streams take `self` by `Pin<Self>`, rather than `&mut Self`.
+    /// This allows types which are not [`Unpin`](::std::marker::Unpin) to guarantee
+    /// that they won't be moved after being polled. Since they won't be moved, it's
+    /// possible for them to safely contain references to themselves.
+    ///
+    /// The most common examples of such self-referential `StableStream`s are
+    /// `#[async_stream(item = Foo)]` functions.
+    ///
+    /// All types which implement `Stream` also implement `StableStream` automatically.
     pub trait StableStream {
+        /// A successful value
         type Item;
+        /// An error
         type Error;
 
+        /// Attempt to resolve the stream to the next value, registering the current task
+        /// for wakeup if the value is not yet available.
+        ///
+        /// This method takes `self` by `Pin`, and so calling it requires putting `Self`
+        /// in a [`PinBox`](::std::boxed::PinBox) using the `pin` method, or otherwise
+        /// guaranteeing that the location of `self` will not change after a call to `poll`.
         fn poll_next(self: Pin<Self>, ctx: &mut task::Context) -> Poll<Option<Self::Item>, Self::Error>;
 
+        /// Pin the stream to a particular location by placing it on the heap.
         #[cfg(feature = "std")]
         fn pin<'a>(self) -> PinBox<Stream<Item = Self::Item, Error = Self::Error> + Send + 'a>
             where Self: Send + Sized + 'a
         {
             PinBox::new(unsafe { UnsafePin::new(self) })
         }
 
+        /// Pin the stream to a particular location by placing it on the heap.
+        ///
+        /// This method is the same as `pin`, but doesn't require that `Self` can be
+        /// safely sent across threads. `pin` should be preferred where possible.
         #[cfg(feature = "std")]
         fn pin_local<'a>(self) -> PinBox<Stream<Item = Self::Item, Error = Self::Error> + 'a>
             where Self: Sized + 'a

futures/src/lib.rs

@@ -401,6 +401,87 @@ pub mod task {
 
 #[cfg(feature = "nightly")]
 pub mod stable {
+    //! `async/await` futures which can be pinned to a particular location.
+    //!
+    //! This module contains:
+    //!
+    //! - The [`StableFuture`](::StableFuture) and [`StableStream`](::StableStream)
+    //! traits which allow for immovable, self-referential `Future`s and `Streams`.
+    //!
+    //! - The [`StableExecutor`](::StableExecutor) trait for `Executor`s which
+    //! take [`PinBox`](::std::boxed:PinBox)ed `Future`s.
+    //!
+    //! - A [`block_on_stable`](::block_on_stable) function for blocking on
+    //! `StableFuture`s.
+    //!
+    //! These immovable future types are most commonly used with the async/await
+    //! macros, which are included in the prelude. These macros can be used to
+    //! write asynchronous code in an ergonomic blocking style:
+    //!
+    //! ```rust
+    //! /// A simple async function which returns immediately once polled:
+    //! #[async]
+    //! fn foo() -> Result<i32, i32> {
+    //!     Ok(1)
+    //! }
+    //!
+    //! /// Async functions can `await!` the result of other async functions:
+    //! #[async]
+    //! fn bar() -> Result<i32, i32> {
+    //!     let foo_num = await!(foo())?;
+    //!     Ok(foo_num + 5)
+    //! }
+    //!
+    //! /// Async functions can also choose to return a `Box`ed `Future` type.
+    //! /// To opt into `Send`able futures, use `#[async(boxed, send)]`.
+    //! #[async(boxed)]
+    //! fn boxed(x: i32) -> Result<i32, i32> {
+    //!     Ok(
+    //!         await!(foo())? + await!(bar()) + x
+    //!     )
+    //! }
+    //!
+    //! /// Async expressions can also be written in `async_block!`s:
+    //! fn async_block() -> impl StableFuture<Item = i32, Error = i32> {
+    //!     println!("Runs before the future is returned");
+    //!     async_block! { 
+    //!         println!("Runs the first time the future is polled");
+    //!         Ok(5)
+    //!     }
+    //! }
+    //!
+    //! /// The futures that result from async functions can be pinned and used
+    //! /// with other `Future` combinators:
+    //! #[async]
+    //! fn join_two_futures() -> Result<(i32, i32), i32> {
+    //!     let joined = foo().pin().join(bar().pin());
+    //!     await!(joined)
+    //! }
+    //!
+    //! /// Streams can also be written in this style using the
+    //! /// `#[async_stream(item = ItemType)]` macro. The `stream_yield!`
+    //! /// macro is used to yield elements, and the `async_stream_block!`
+    //! /// macro can be used to write async streams inside other functions:
+    //! #[async_stream(boxed, send, item = u64)]
+    //! fn stream_boxed() -> Result<(), i32> {
+    //!     let foo_result = await!(foo())?;
+    //!     stream_yield!(foo_result as u64);
+    //!     stream_yield!(22);
+    //!     Ok(())
+    //! }
+    //!
+    //! /// Finally #[async] can be used on `for` loops to loop over the results
+    //! /// of a stream:
+    //! #[async]
+    //! fn async_for() -> Result<(), i32> {
+    //!     #[async]
+    //!     for i in stream_boxed() {
+    //!         println!("yielded {}", i);
+    //!     }
+    //!     Ok(())
+    //! }
+    //! ```
+
     pub use futures_stable::{StableFuture, StableStream};
 
     #[cfg(feature = "std")]