Repository: tokio-rs/tokio
File: tokio/src/runtime/coop.rs (Rust)

Code before:
                    *num -= 1;

                    let hit_zero = *num == 0;

                    BudgetDecrement { success: true, hit_zero }
                } else {
                    BudgetDecrement { success: false, hit_zero: false }
                }
            } else {
                BudgetDecrement { success: true, hit_zero: false }
            }
        }

        fn is_unconstrained(self) -> bool {
            self.0.is_none()
        }
    }

    pin_project! {
        /// A future type that calls `poll_proceed` before polling the inner future to check if the
        /// inner future has exceeded its budget. If the inner future resolves, this will
        /// automatically call `RestoreOnPending::made_progress` before resolving this future with
        /// the result of the inner one. If polling the inner future is pending, polling this future
        /// type will also return a `Poll::Pending`.
        #[must_use = "futures do nothing unless polled"]
        pub(crate) struct BudgetConstraintFuture<F: Future> {
            #[pin]
            pub(crate) fut: F,
        }
    }

    impl<F: Future> Future for BudgetConstraintFuture<F> {
        type Output = F::Output;

        fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> {
            let coop = ready!(poll_proceed(cx));
            let me = self.project();
            if let Poll::Ready(ret) = me.fut.poll(cx) {
                coop.made_progress();
                Poll::Ready(ret)
            } else {
                Poll::Pending
            }
        }
    }

    /// Run a future with a budget constraint for cooperative scheduling.
    /// If the future exceeds its budget while being polled, control is yielded back to the
    /// runtime.
    #[inline]
    pub(crate) async fn budget_constraint<F: Future>(fut: F) -> F::Output {

Review comment (suggestion):
This isn't publicly visible, so it's not a big deal here, but generally the convention is that documentation should start with one *short* line. If more explanation is needed, it can go in a separate paragraph. This is because when structs are shown in documentation, the first line is used as a summary in some cases, and the summary should be short.

Code after:
                    *num -= 1;

                    let hit_zero = *num == 0;

                    BudgetDecrement { success: true, hit_zero }
                } else {
                    BudgetDecrement { success: false, hit_zero: false }
                }
            } else {
                BudgetDecrement { success: true, hit_zero: false }
            }
        }

        fn is_unconstrained(self) -> bool {
            self.0.is_none()
        }
    }

    pin_project! {
        /// Future wrapper to ensure cooperative scheduling.
        ///
        /// When being polled `poll_proceed` is called before the inner future is polled to check
        /// if the inner future has exceeded its budget. If the inner future resolves, this will
        /// automatically call `RestoreOnPending::made_progress` before resolving this future with
        /// the result of the inner one. If polling the inner future is pending, polling this future
        /// type will also return a `Poll::Pending`.
        #[must_use = "futures do nothing unless polled"]
        pub(crate) struct Coop<F: Future> {
            #[pin]
            pub(crate) fut: F,
        }
    }

    impl<F: Future> Future for Coop<F> {
        type Output = F::Output;

        fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> {
            let coop = ready!(poll_proceed(cx));
            let me = self.project();
            if let Poll::Ready(ret) = me.fut.poll(cx) {
                coop.made_progress();
                Poll::Ready(ret)
            } else {
                Poll::Pending
            }
        }
    }

    /// Run a future with a budget constraint for cooperative scheduling.
    /// If the future exceeds its budget while being polled, control is yielded back to the
    /// runtime.