ExecutorExt, spawn! and spawn_with_handle!

futures-executor/src/lib.rs

@@ -33,7 +33,4 @@ if_std! {
 
     mod enter;
     pub use crate::enter::{enter, Enter, EnterError};
-
-    mod spawn;
-    pub use crate::spawn::{spawn, Spawn, spawn_with_handle, SpawnWithHandle, JoinHandle};
 }

futures-util/src/async_await/mod.rs

@@ -20,6 +20,9 @@ mod join;
 // Primary export is a macro
 mod select;
 
+// Primary export is a macro
+mod spawn;
+
 #[doc(hidden)]
 #[inline(always)]
 pub fn assert_unpin<T: Future + Unpin>(_: &T) {}

futures-util/src/async_await/spawn.rs

@@ -0,0 +1,61 @@
+/// Spawns a task onto the context's executor that polls the given future with
+/// output `()` to completion.
+///
+/// This macro returns a [`Result`] that contains a
+/// [`SpawnError`](crate::task::SpawnError) if spawning fails.
+///
+/// You can use [`spawn_with_handle!`] if you want to spawn a future
+/// with output other than `()` or if you want to be able to await its
+/// completion.
+///
+/// ```
+/// #![feature(async_await, await_macro, futures_api)]
+/// #[macro_use] extern crate futures;
+/// # futures::executor::block_on(async {
+///
+/// let future = async { /* ... */ };
+/// spawn!(future).unwrap();
+/// # });
+/// ```
+#[macro_export]
+macro_rules! spawn {
+    ($future:expr) => {
+        await!($crate::future::lazy(|cx| {
+            use $crate::task::ExecutorExt;
+            cx.executor().spawn($future)
+        }))
+    }
+}
+
+/// Spawns a task onto the context's executor that polls the given future to
+/// completion and returns a future that resolves to the spawned future's
+/// output.
+///
+/// This macro returns a [`Result`] that contains a
+/// [`JoinHandle`](crate::task::JoinHandle), or, if spawning fails, a
+/// [`SpawnError`](crate::task::SpawnError).
+/// [`JoinHandle`](crate::task::JoinHandle) is a future that resolves
+/// to the output of the spawned future
+///
+/// # Examples
+///
+/// ```
+/// #![feature(async_await, await_macro, futures_api)]
+/// #[macro_use] extern crate futures;
+/// # futures::executor::block_on(async {
+/// use futures::future;
+///
+/// let future = future::ready(1);
+/// let join_handle = spawn_with_handle!(future).unwrap();
+/// assert_eq!(await!(join_handle), 1);
+/// # });
+/// ```
+#[macro_export]
+macro_rules! spawn_with_handle {
+    ($future:expr) => {
+        await!($crate::future::lazy(|cx| {
+            use $crate::task::ExecutorExt;
+            cx.executor().spawn_with_handle($future)
+        }))
+    }
+}

futures-util/src/future/mod.rs

@@ -659,16 +659,30 @@ pub trait FutureExt: Future {
     ///
     /// ```
     /// #![feature(async_await, await_macro, futures_api)]
+    /// #[macro_use] extern crate futures;
     /// # futures::executor::block_on(async {
-    /// use futures::executor::{spawn_with_handle, ThreadPool};
-    /// use futures::future::{self, FutureExt};
+    /// use futures::executor::ThreadPool;
+    /// use futures::future::FutureExt;
+    /// use std::thread;
+    /// # let (tx, rx) = futures::channel::oneshot::channel();
     ///
-    /// let pool = ThreadPool::new().expect("unable to create threadpool");
-    /// let future = spawn_with_handle(future::ready(3))
-    ///     .with_executor(pool)
-    ///     .flatten();
-    /// assert_eq!(await!(future), 3);
-    /// # });
+    /// let pool = ThreadPool::builder()
+    ///     .name_prefix("my-pool-")
+    ///     .pool_size(1)
+    ///     .create().unwrap();
+    ///
+    ///  let val = await!((async {
+    ///      assert_ne!(thread::current().name(), Some("my-pool-0"));
+    ///
+    ///      // Spawned task runs on the executor specified via `with_executor`
+    ///      spawn!(async {
+    ///          assert_eq!(thread::current().name(), Some("my-pool-0"));
+    ///          # tx.send("ran").unwrap();
+    ///      }).unwrap();
+    ///  }).with_executor(pool));
+    ///
+    ///  # assert_eq!(await!(rx), Ok("ran"))
+    ///  # })
     /// ```
     fn with_executor<E>(self, executor: E) -> WithExecutor<Self, E>
         where Self: Sized,