Improve naming in iteration API

Renamed:
Policy -> LoopPolicy, for more instant legibility in docs
Policy::begin -> LoopPolicy::enter, clearer meaning

futures-core/src/iteration.rs

@@ -3,13 +3,13 @@
 use core::num::NonZeroU32;
 
 /// Iteration policy checker for eager polling loops.
-pub trait Policy {
+pub trait LoopPolicy {
     /// State for checking iterations over the lifetime of a polling loop.
     type State;
 
     /// Called before entering the loop to initialize state for
     /// iteration checks.
-    fn begin(&mut self) -> Self::State;
+    fn enter(&mut self) -> Self::State;
 
     /// Called at the end of each iteration to update the check state
     /// and decide whether the poll function should yield, that is,
@@ -20,19 +20,19 @@ pub trait Policy {
 
 /// An unlimited iteration policy.
 ///
-/// The [`Policy`] implementation for a value of this token type bypasses
+/// The [`LoopPolicy`] implementation for a value of this token type bypasses
 /// any checking on iterations of a polling loop, allowing it to continue
 /// indefinitely until ended by logic in the loop body (normally when
 /// an asynchronous source is pending or the poll resolves with an output
 /// value).
 #[derive(Debug)]
 pub struct Unlimited {}
 
-impl Policy for Unlimited {
+impl LoopPolicy for Unlimited {
     type State = ();
 
     #[inline]
-    fn begin(&mut self) {}
+    fn enter(&mut self) {}
 
     #[inline]
     fn yield_check(&mut self, _: &mut ()) -> bool {
@@ -42,9 +42,9 @@ impl Policy for Unlimited {
 
 /// An iteration policy with a limit on the number of consecutive iterations.
 ///
-/// The [`Policy`] implementation of this type runs a counter on the number
+/// The [`LoopPolicy`] implementation of this type runs a counter on the number
 /// of iterations and, when the given limit is reached, instructs the
-/// [`yield_check`](Policy::yield_check) caller to yield.
+/// [`yield_check`](LoopPolicy::yield_check) caller to yield.
 #[derive(Debug, PartialEq, Eq, PartialOrd, Ord)]
 pub struct Limit(NonZeroU32);
 
@@ -56,11 +56,11 @@ impl Limit {
     }
 }
 
-impl Policy for Limit {
+impl LoopPolicy for Limit {
     type State = u32;
 
     #[inline]
-    fn begin(&mut self) -> u32 {
+    fn enter(&mut self) -> u32 {
         self.0.into()
     }
 

futures-core/src/task/poll.rs

@@ -22,11 +22,11 @@ macro_rules! ready {
 /// potentially starving other asynchronous operations in the same task
 /// from being polled.
 ///
-/// To prevent this, `poll_loop!` uses the [`Policy`] protocol to check
+/// To prevent this, `poll_loop!` uses the [`LoopPolicy`] protocol to check
 /// at the end of each iteration whether to yield to the task by returning
 /// [`Pending`].
 /// The first parameter of the macro receives a mutable pointer to the
-/// iteration policy checker implementing `Policy`.
+/// iteration policy checker implementing `LoopPolicy`.
 /// The second parameter receives the reference to the
 /// [`Context`] passed to the poll function.
 /// The body of a loop iteration is given in the third parameter.
@@ -42,17 +42,17 @@ macro_rules! ready {
 /// [`Context`]: core::task::Context
 /// [`Pending`]: core::task::Poll::Pending
 /// [`Ready`]: core::task::Poll::Ready
-/// [`Policy`]: iteration::Policy
+/// [`LoopPolicy`]: iteration::LoopPolicy
 #[macro_export]
 macro_rules! poll_loop {
     {$policy:expr, $cx:expr, $body:expr} => {
         {
             #[allow(clippy::deref_addrof)]
             let policy = &mut *$policy;
-            let mut state = $crate::iteration::Policy::begin(policy);
+            let mut state = $crate::iteration::LoopPolicy::enter(policy);
             loop {
                 { $body }
-                if $crate::iteration::Policy::yield_check(policy, &mut state) {
+                if $crate::iteration::LoopPolicy::yield_check(policy, &mut state) {
                     $crate::core_reexport::task::Context::waker($cx).wake_by_ref();
                     return $crate::core_reexport::task::Poll::Pending;
                 }

futures/src/lib.rs

@@ -341,19 +341,19 @@ pub mod io {
 pub mod iteration {
     //! Utilities for implementing iterative polling in a cooperative way.
     //!
-    //! This module provides the [`Policy`] trait and its implementations
+    //! This module provides the [`LoopPolicy`] trait and its implementations
     //! that can be used to tune behavior of eager polling loops in a
     //! polymorphic way.
     //!
-    //! An object implementing `Policy` is used by the [`poll_loop!`] macro,
+    //! An object implementing `LoopPolicy` is used by the [`poll_loop!`] macro,
     //! normally as a member of a structure implementing an asynchronous polling
     //! API such as [`Future`], where a poll function runs a loop that can
     //! potentially be saturated by asynchronous sources readily yielding
     //! data for many consecutive iterations.
     //!
     //! [`Future`]: core::future::Future
 
-    pub use futures_core::iteration::{Policy, Limit, Unlimited};
+    pub use futures_core::iteration::{LoopPolicy, Limit, Unlimited};
 }
 
 #[cfg_attr(feature = "cfg-target-has-atomic", cfg(target_has_atomic = "ptr"))]