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,5 +20,8 @@ mod join;
 // Primary export is a macro
 mod select;
 
+// Primary export is a macro
+mod spawn;
+
 #[doc(hidden)]
 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

@@ -639,16 +639,31 @@ 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};
- ///
- /// 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);
- /// # });
+ /// use futures::executor::ThreadPool;
+ /// use futures::future::FutureExt;
+ /// use std::thread;
+ /// # let (tx, rx) = futures::channel::oneshot::channel();
+ ///
+ /// 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`
+ /// let future = async {
+ /// assert_eq!(thread::current().name(), Some("my-pool-0"));
+ /// # tx.send("ran").unwrap();
+ /// };
+ /// spawn!(future).unwrap();
+ /// }).with_executor(pool));
+ ///
+ /// # assert_eq!(await!(rx), Ok("ran"))
+ /// # })
  /// ```
  fn with_executor<E>(self, executor: E) -> WithExecutor<Self, E>
  where Self: Sized,