Skip to main content

risingwave_stream/executor/project/
inflight_rows.rs

1// Copyright 2026 RisingWave Labs
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7//     http://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14
15use std::sync::Arc;
16use std::sync::atomic::{AtomicUsize, Ordering};
17
18use tokio::sync::Notify;
19
20/// A soft row budget: admit one whole chunk while usage is below the limit. Unlike acquiring
21/// multiple semaphore permits, this lets a chunk larger than the limit make progress. Once usage
22/// reaches the limit, further nonempty chunks wait for evaluation to finish and release rows.
23pub(super) struct InflightRows {
24    limit: usize,
25    used: AtomicUsize,
26    changed: Notify,
27}
28
29impl InflightRows {
30    pub(super) fn new(limit: usize) -> Self {
31        assert!(limit > 0);
32        Self {
33            limit,
34            used: AtomicUsize::new(0),
35            changed: Notify::new(),
36        }
37    }
38
39    #[cfg(test)]
40    pub(super) fn used_rows(&self) -> usize {
41        self.used.load(Ordering::Acquire)
42    }
43
44    pub(super) async fn acquire(self: &Arc<Self>, rows: usize) -> InflightRowsPermit {
45        loop {
46            // Register before inspecting usage, so a concurrent release cannot lose a wakeup.
47            let changed = self.changed.notified();
48            if rows == 0
49                || self
50                    .used
51                    .fetch_update(Ordering::AcqRel, Ordering::Acquire, |used| {
52                        (used < self.limit).then(|| {
53                            used.checked_add(rows)
54                                .expect("in-flight row count overflow")
55                        })
56                    })
57                    .is_ok()
58            {
59                return InflightRowsPermit {
60                    budget: self.clone(),
61                    rows,
62                };
63            }
64            changed.await;
65        }
66    }
67}
68
69pub(super) struct InflightRowsPermit {
70    budget: Arc<InflightRows>,
71    rows: usize,
72}
73
74impl Drop for InflightRowsPermit {
75    fn drop(&mut self) {
76        self.budget.used.fetch_sub(self.rows, Ordering::AcqRel);
77        self.budget.changed.notify_waiters();
78    }
79}
80
81#[cfg(test)]
82mod tests {
83    use futures::{FutureExt, poll};
84
85    use super::*;
86
87    #[tokio::test]
88    async fn variable_chunks_overshoot_only_once() {
89        let budget = Arc::new(InflightRows::new(5));
90        let first = budget.acquire(3).await;
91        let second = budget.acquire(4).await;
92        assert_eq!(budget.used.load(Ordering::Acquire), 7);
93        let third = budget.acquire(8);
94        tokio::pin!(third);
95        assert!(poll!(&mut third).is_pending());
96        // Empty chunks never consume budget, even while it is exceeded.
97        drop(budget.acquire(0).await);
98        assert_eq!(budget.used.load(Ordering::Acquire), 7);
99        drop(first);
100        let third = third.await;
101        assert_eq!(budget.used.load(Ordering::Acquire), 12);
102        assert!(budget.acquire(1).now_or_never().is_none());
103        drop(second);
104        assert!(budget.acquire(1).now_or_never().is_none());
105        drop(third);
106        assert_eq!(budget.used.load(Ordering::Acquire), 0);
107        drop(budget.acquire(100).await);
108        assert_eq!(budget.used.load(Ordering::Acquire), 0);
109    }
110
111    #[tokio::test]
112    async fn release_on_error_and_cancellation() {
113        let budget = Arc::new(InflightRows::new(2));
114        let failed: Result<(), ()> = async {
115            let _permit = budget.acquire(3).await;
116            Err(())
117        }
118        .await;
119        assert!(failed.is_err());
120        assert_eq!(budget.used.load(Ordering::Acquire), 0);
121
122        let running = async {
123            let _permit = budget.acquire(4).await;
124            std::future::pending::<()>().await;
125        };
126        let mut running = Box::pin(running);
127        assert!(poll!(&mut running).is_pending());
128        assert_eq!(budget.used.load(Ordering::Acquire), 4);
129        // Cancelling a waiter must not return another chunk's permits.
130        assert!(budget.acquire(1).now_or_never().is_none());
131        assert_eq!(budget.used.load(Ordering::Acquire), 4);
132        drop(running);
133        assert_eq!(budget.used.load(Ordering::Acquire), 0);
134        drop(budget.acquire(2).await);
135    }
136}