diff --git a/futures-executor/src/local_pool.rs b/futures-executor/src/local_pool.rs index ac5cf23000..8bf7246266 100644 --- a/futures-executor/src/local_pool.rs +++ b/futures-executor/src/local_pool.rs @@ -170,14 +170,14 @@ impl LocalPool { /// ``` /// use futures::executor::LocalPool; /// use futures::task::LocalSpawnExt; - /// use futures::future::{ready, empty}; + /// use futures::future::{ready, pending}; /// /// let mut pool = LocalPool::new(); /// let mut spawner = pool.spawner(); /// /// spawner.spawn_local(ready(())).unwrap(); /// spawner.spawn_local(ready(())).unwrap(); - /// spawner.spawn_local(empty()).unwrap(); + /// spawner.spawn_local(pending()).unwrap(); /// /// // Run the two ready tasks and return true for them. /// pool.try_run_one(); // returns true after completing one of the ready futures @@ -210,14 +210,14 @@ impl LocalPool { /// ``` /// use futures::executor::LocalPool; /// use futures::task::LocalSpawnExt; - /// use futures::future::{ready, empty}; + /// use futures::future::{ready, pending}; /// /// let mut pool = LocalPool::new(); /// let mut spawner = pool.spawner(); /// /// spawner.spawn_local(ready(())).unwrap(); /// spawner.spawn_local(ready(())).unwrap(); - /// spawner.spawn_local(empty()).unwrap(); + /// spawner.spawn_local(pending()).unwrap(); /// /// // Runs the two ready task and returns. /// // The empty task remains in the pool. diff --git a/futures-test/src/future/assert_unmoved.rs b/futures-test/src/future/assert_unmoved.rs index 2f769df1fa..74f92c626b 100644 --- a/futures-test/src/future/assert_unmoved.rs +++ b/futures-test/src/future/assert_unmoved.rs @@ -63,7 +63,7 @@ impl Drop for AssertUnmoved { mod tests { use futures_core::future::Future; use futures_core::task::{Context, Poll}; - use futures_util::future::empty; + use futures_util::future::pending; use futures_util::task::noop_waker; use std::pin::Pin; @@ -72,7 +72,7 @@ mod tests { #[test] fn dont_panic_when_not_polled() { // This shouldn't panic. - let future = AssertUnmoved::new(empty::<()>()); + let future = AssertUnmoved::new(pending::<()>()); drop(future); } @@ -84,7 +84,7 @@ mod tests { let mut cx = Context::from_waker(&waker); // First we allocate the future on the stack and poll it. - let mut future = AssertUnmoved::new(empty::<()>()); + let mut future = AssertUnmoved::new(pending::<()>()); let pinned_future = unsafe { Pin::new_unchecked(&mut future) }; assert_eq!(pinned_future.poll(&mut cx), Poll::Pending); diff --git a/futures-util/src/async_await/select_mod.rs b/futures-util/src/async_await/select_mod.rs index 9c49108730..67efdca6a2 100644 --- a/futures-util/src/async_await/select_mod.rs +++ b/futures-util/src/async_await/select_mod.rs @@ -32,7 +32,7 @@ macro_rules! document_select_macro { /// use futures::future; /// use futures::select; /// let mut a = future::ready(4); - /// let mut b = future::empty::<()>(); + /// let mut b = future::pending::<()>(); /// /// let res = select! { /// a_res = a => a_res + 1, @@ -49,7 +49,7 @@ macro_rules! document_select_macro { /// use futures::stream::{self, StreamExt}; /// use futures::select; /// let mut st = stream::iter(vec![2]).fuse(); - /// let mut fut = future::empty::<()>(); + /// let mut fut = future::pending::<()>(); /// /// select! { /// x = st.next() => assert_eq!(Some(2), x), diff --git a/futures-util/src/future/mod.rs b/futures-util/src/future/mod.rs index 242381f1fa..f44bfb0cdb 100644 --- a/futures-util/src/future/mod.rs +++ b/futures-util/src/future/mod.rs @@ -17,12 +17,12 @@ use futures_core::future::{BoxFuture, LocalBoxFuture}; pub use futures_core::future::FusedFuture; // Primitive futures -mod empty; -pub use self::empty::{empty, Empty}; - mod lazy; pub use self::lazy::{lazy, Lazy}; +mod pending; +pub use self::pending::{pending, Pending}; + mod maybe_done; pub use self::maybe_done::{maybe_done, MaybeDone}; diff --git a/futures-util/src/future/empty.rs b/futures-util/src/future/pending.rs similarity index 65% rename from futures-util/src/future/empty.rs rename to futures-util/src/future/pending.rs index d7e6cde75c..5e41597a7e 100644 --- a/futures-util/src/future/empty.rs +++ b/futures-util/src/future/pending.rs @@ -1,17 +1,19 @@ use core::marker; use core::pin::Pin; -use futures_core::future::{Future, FusedFuture}; +use futures_core::future::{FusedFuture, Future}; use futures_core::task::{Context, Poll}; -/// Future for the [`empty`] function. +/// Future for the [`pending()`] function. #[derive(Debug)] #[must_use = "futures do nothing unless you `.await` or poll them"] -pub struct Empty { +pub struct Pending { _data: marker::PhantomData, } -impl FusedFuture for Empty { - fn is_terminated(&self) -> bool { false } +impl FusedFuture for Pending { + fn is_terminated(&self) -> bool { + false + } } /// Creates a future which never resolves, representing a computation that never @@ -26,16 +28,18 @@ impl FusedFuture for Empty { /// # futures::executor::block_on(async { /// use futures::future; /// -/// let future = future::empty(); +/// let future = future::pending(); /// let () = future.await; /// unreachable!(); /// # }); /// ``` -pub fn empty() -> Empty { - Empty { _data: marker::PhantomData } +pub fn pending() -> Pending { + Pending { + _data: marker::PhantomData, + } } -impl Future for Empty { +impl Future for Pending { type Output = T; fn poll(self: Pin<&mut Self>, _: &mut Context<'_>) -> Poll { diff --git a/futures-util/src/stream/mod.rs b/futures-util/src/stream/mod.rs index 7258a673aa..f7ee3129bd 100644 --- a/futures-util/src/stream/mod.rs +++ b/futures-util/src/stream/mod.rs @@ -76,6 +76,9 @@ pub use self::once::{once, Once}; mod peek; pub use self::peek::Peekable; +mod pending; +pub use self::pending::{pending, Pending}; + mod poll_fn; pub use self::poll_fn::{poll_fn, PollFn}; diff --git a/futures-util/src/stream/pending.rs b/futures-util/src/stream/pending.rs new file mode 100644 index 0000000000..6d167f2b4a --- /dev/null +++ b/futures-util/src/stream/pending.rs @@ -0,0 +1,27 @@ +use core::marker; +use core::pin::Pin; + +use futures_core::{Stream, Poll}; +use futures_core::task; + +/// Stream for the [`pending()`] function. +#[derive(Debug)] +#[must_use = "streams do nothing unless polled"] +pub struct Pending { + _data: marker::PhantomData, +} + +/// Creates a stream which never returns any elements. +/// +/// The returned stream will always return `Pending` when polled. +pub fn pending() -> Pending { + Pending { _data: marker::PhantomData } +} + +impl Stream for Pending { + type Item = T; + + fn poll_next(self: Pin<&mut Self>, _: &mut task::Context<'_>) -> Poll> { + Poll::Pending + } +} diff --git a/futures/src/lib.rs b/futures/src/lib.rs index 2c85f743e8..127c736c7b 100644 --- a/futures/src/lib.rs +++ b/futures/src/lib.rs @@ -211,9 +211,9 @@ pub mod future { pub use futures_core::future::BoxFuture; pub use futures_util::future::{ - empty, Empty, lazy, Lazy, maybe_done, MaybeDone, + pending, Pending, poll_fn, PollFn, ready, ok, err, Ready, select, Select, diff --git a/futures/tests/futures_unordered.rs b/futures/tests/futures_unordered.rs index 777ad46f51..16553665d4 100644 --- a/futures/tests/futures_unordered.rs +++ b/futures/tests/futures_unordered.rs @@ -3,9 +3,9 @@ use futures::executor::{block_on, block_on_stream}; use futures::future::{self, join, Future, FutureExt}; use futures::stream::{FusedStream, FuturesUnordered, StreamExt}; use futures::task::Poll; -use futures_test::{assert_stream_done, assert_stream_next}; use futures_test::future::FutureTestExt; use futures_test::task::noop_context; +use futures_test::{assert_stream_done, assert_stream_next}; #[test] fn is_terminated() { @@ -40,7 +40,11 @@ fn works_1() { let (b_tx, b_rx) = oneshot::channel::(); let (c_tx, c_rx) = oneshot::channel::(); - let mut iter = block_on_stream(vec![a_rx, b_rx, c_rx].into_iter().collect::>()); + let mut iter = block_on_stream( + vec![a_rx, b_rx, c_rx] + .into_iter() + .collect::>(), + ); b_tx.send(99).unwrap(); assert_eq!(Some(Ok(99)), iter.next()); @@ -61,7 +65,9 @@ fn works_2() { let mut stream = vec![ a_rx.boxed(), join(b_rx, c_rx).map(|(a, b)| Ok(a? + b?)).boxed(), - ].into_iter().collect::>(); + ] + .into_iter() + .collect::>(); a_tx.send(9).unwrap(); b_tx.send(10).unwrap(); @@ -78,10 +84,12 @@ fn from_iterator() { let stream = vec![ future::ready::(1), future::ready::(2), - future::ready::(3) - ].into_iter().collect::>(); + future::ready::(3), + ] + .into_iter() + .collect::>(); assert_eq!(stream.len(), 3); - assert_eq!(block_on(stream.collect::>()), vec![1,2,3]); + assert_eq!(block_on(stream.collect::>()), vec![1, 2, 3]); } #[test] @@ -93,7 +101,9 @@ fn finished_future() { let mut stream = vec![ Box::new(a_rx) as Box> + Unpin>, Box::new(future::select(b_rx, c_rx).map(|e| e.factor_first().0)) as _, - ].into_iter().collect::>(); + ] + .into_iter() + .collect::>(); let cx = &mut noop_context(); for _ in 0..10 { @@ -113,7 +123,9 @@ fn iter_mut_cancel() { let (b_tx, b_rx) = oneshot::channel::(); let (c_tx, c_rx) = oneshot::channel::(); - let mut stream = vec![a_rx, b_rx, c_rx].into_iter().collect::>(); + let mut stream = vec![a_rx, b_rx, c_rx] + .into_iter() + .collect::>(); for rx in stream.iter_mut() { rx.close(); @@ -134,10 +146,12 @@ fn iter_mut_cancel() { #[test] fn iter_mut_len() { let mut stream = vec![ - future::empty::<()>(), - future::empty::<()>(), - future::empty::<()>() - ].into_iter().collect::>(); + future::pending::<()>(), + future::pending::<()>(), + future::pending::<()>(), + ] + .into_iter() + .collect::>(); let mut iter_mut = stream.iter_mut(); assert_eq!(iter_mut.len(), 3); diff --git a/futures/tests/unfold.rs b/futures/tests/unfold.rs index 377647fa22..95722cf8a6 100644 --- a/futures/tests/unfold.rs +++ b/futures/tests/unfold.rs @@ -1,10 +1,10 @@ use futures::future; use futures::stream; +use futures_test::future::FutureTestExt; use futures_test::{ - assert_stream_pending, assert_stream_next, assert_stream_done, + assert_stream_done, assert_stream_next, assert_stream_pending, }; -use futures_test::future::FutureTestExt; #[test] fn unfold1() {