Skip to main content

alpha2_render/cpu/
workers.rs

1//! The CPU renderer's threads. Each pass splits rows into bands, each written by one thread, so
2//! results do not depend on the thread count.
3
4/// Approximate pixels per band: enough to amortize scheduling, small enough to stay in cache.
5const BAND_PIXELS: usize = 16_384;
6
7type Progress = std::sync::Arc<dyn Fn() + Send + Sync>;
8
9std::thread_local! {
10    static BAND_PROGRESS: std::cell::RefCell<Option<Progress>> =
11        const { std::cell::RefCell::new(None) };
12}
13
14/// Calls `progress` once per band of every pass the CPU renderer draws for the calling thread,
15/// from whichever thread draws the band, until the guard drops. A watcher of the caller then sees
16/// a long frame progress.
17#[must_use = "the report ends when the guard drops"]
18pub fn report_band_progress(progress: Progress) -> BandProgress {
19    let previous = BAND_PROGRESS.with(|current| current.replace(Some(progress)));
20    BandProgress {
21        previous,
22        thread: std::marker::PhantomData,
23    }
24}
25
26/// Ends a [`report_band_progress`] report, restoring the one before it.
27pub struct BandProgress {
28    previous: Option<Progress>,
29    thread: std::marker::PhantomData<*const ()>,
30}
31
32impl Drop for BandProgress {
33    fn drop(&mut self) {
34        let previous = self.previous.take();
35        BAND_PROGRESS.with(|current| {
36            current.replace(previous);
37        });
38    }
39}
40
41fn band_progress() -> impl Fn() + Send + Sync {
42    let progress = BAND_PROGRESS.with(|current| current.borrow().clone());
43    move || {
44        if let Some(progress) = &progress {
45            progress();
46        }
47    }
48}
49
50/// The threads one CPU renderer draws with.
51pub(crate) struct Workers {
52    #[cfg(not(target_arch = "wasm32"))]
53    pool: Option<rayon::ThreadPool>,
54    threads: usize,
55    /// Rows of every band in place of [`band_rows`], so tests can move band seams.
56    fixed_rows: Option<usize>,
57}
58
59impl std::fmt::Debug for Workers {
60    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
61        formatter
62            .debug_struct("Workers")
63            .field("threads", &self.threads)
64            .finish_non_exhaustive()
65    }
66}
67
68impl Workers {
69    /// `threads` workers (one means the calling thread); falls back to the calling thread if the
70    /// pool cannot start.
71    pub(crate) fn new(threads: usize) -> Self {
72        let threads = threads.max(1);
73        #[cfg(not(target_arch = "wasm32"))]
74        {
75            let pool = (threads > 1)
76                .then(|| {
77                    rayon::ThreadPoolBuilder::new()
78                        .num_threads(threads)
79                        .thread_name(|index| format!("alpha2-cpu-render-{index}"))
80                        .build()
81                        .ok()
82                })
83                .flatten();
84            let threads = if pool.is_some() { threads } else { 1 };
85            Self {
86                pool,
87                threads,
88                fixed_rows: None,
89            }
90        }
91        #[cfg(target_arch = "wasm32")]
92        {
93            let _ = threads;
94            Self {
95                threads: 1,
96                fixed_rows: None,
97            }
98        }
99    }
100
101    /// As [`Self::new`], with every band `rows` rows high (`usize::MAX` for one band).
102    #[cfg(test)]
103    pub(crate) fn with_band_rows(threads: usize, rows: usize) -> Self {
104        Self {
105            fixed_rows: Some(rows.max(1)),
106            ..Self::new(threads)
107        }
108    }
109
110    /// Rows per band for an image `width` pixels wide.
111    pub(crate) fn band_rows(&self, width: usize) -> usize {
112        self.fixed_rows.unwrap_or_else(|| band_rows(width))
113    }
114
115    pub(crate) const fn threads(&self) -> usize {
116        self.threads
117    }
118
119    /// Calls `draw(first_row, rows)` in parallel for each band of whole rows of `pixels`, an image
120    /// `width` wide; `first_row` counts from the start of `pixels`.
121    // On wasm there is no pool: every band runs on the calling thread.
122    #[cfg_attr(target_arch = "wasm32", allow(clippy::unused_self))]
123    pub(crate) fn bands<T: Send>(
124        &self,
125        pixels: &mut [T],
126        width: usize,
127        draw: impl Fn(usize, &mut [T]) + Sync + Send,
128    ) {
129        if width == 0 || pixels.is_empty() {
130            return;
131        }
132        let rows = self.band_rows(width);
133        let progress = band_progress();
134        let draw = |row, chunk: &mut [T]| {
135            progress();
136            draw(row, chunk);
137        };
138        #[cfg(not(target_arch = "wasm32"))]
139        if let Some(pool) = &self.pool {
140            use rayon::prelude::*;
141            pool.install(|| {
142                pixels
143                    .par_chunks_mut(rows.saturating_mul(width))
144                    .enumerate()
145                    .for_each(|(band, chunk)| draw(band * rows, chunk));
146            });
147            return;
148        }
149        for (band, chunk) in pixels.chunks_mut(rows.saturating_mul(width)).enumerate() {
150            draw(band * rows, chunk);
151        }
152    }
153
154    /// As [`Self::bands`], with `draw(scratch, first_row, rows)` reusing one `init()` scratch per
155    /// thread for the bands it draws in this pass.
156    ///
157    /// Which bands share a scratch depends on scheduling, so `draw` must reset everything it
158    /// reads from the scratch at the start of each band.
159    pub(crate) fn bands_with<T: Send, S: Send>(
160        &self,
161        pixels: &mut [T],
162        width: usize,
163        init: impl Fn() -> S + Sync + Send,
164        draw: impl Fn(&mut S, usize, &mut [T]) + Sync + Send,
165    ) {
166        if width == 0 || pixels.is_empty() {
167            return;
168        }
169        let rows = self.band_rows(width);
170        self.chunks_with(pixels, rows.saturating_mul(width), rows, init, draw);
171    }
172
173    /// As [`Self::bands_with`] over `items` that each cover `item_pixels` pixels (one row of
174    /// chroma, say): bands hold whole items, `draw` gets the index of its first item.
175    pub(crate) fn items_with<T: Send, S: Send>(
176        &self,
177        items: &mut [T],
178        item_pixels: usize,
179        init: impl Fn() -> S + Sync + Send,
180        draw: impl Fn(&mut S, usize, &mut [T]) + Sync + Send,
181    ) {
182        if item_pixels == 0 || items.is_empty() {
183            return;
184        }
185        let rows = self.band_rows(item_pixels);
186        self.chunks_with(items, rows, rows, init, draw);
187    }
188
189    /// Calls `draw(scratch, band * step, chunk)` for each `length`-long chunk of `items`.
190    #[cfg_attr(target_arch = "wasm32", allow(clippy::unused_self))]
191    fn chunks_with<T: Send, S: Send>(
192        &self,
193        items: &mut [T],
194        length: usize,
195        step: usize,
196        init: impl Fn() -> S + Sync + Send,
197        draw: impl Fn(&mut S, usize, &mut [T]) + Sync + Send,
198    ) {
199        let progress = band_progress();
200        let draw = |scratch: &mut S, row, chunk: &mut [T]| {
201            progress();
202            draw(scratch, row, chunk);
203        };
204        #[cfg(not(target_arch = "wasm32"))]
205        if let Some(pool) = &self.pool {
206            use rayon::prelude::*;
207            use std::sync::{Mutex, TryLockError};
208            // The last slot serves a caller outside the pool.
209            let slots = (0..=self.threads)
210                .map(|_| Mutex::new(None::<S>))
211                .collect::<Vec<_>>();
212            pool.install(|| {
213                items
214                    .par_chunks_mut(length)
215                    .enumerate()
216                    .for_each(|(band, chunk)| {
217                        let slot = rayon::current_thread_index()
218                            .map_or(self.threads, |index| index.min(self.threads));
219                        match slots[slot].try_lock() {
220                            Ok(mut held) => {
221                                let scratch = held.get_or_insert_with(&init);
222                                draw(scratch, band * step, chunk);
223                            }
224                            // A thread that re-entered the pool while drawing: a scratch of its own.
225                            Err(TryLockError::WouldBlock | TryLockError::Poisoned(_)) => {
226                                draw(&mut init(), band * step, chunk);
227                            }
228                        }
229                    });
230            });
231            return;
232        }
233        let mut scratch = init();
234        for (band, chunk) in items.chunks_mut(length).enumerate() {
235            draw(&mut scratch, band * step, chunk);
236        }
237    }
238
239    /// Calls `job(index)` for every index below `count`, in parallel and in any order.
240    #[cfg_attr(target_arch = "wasm32", allow(clippy::unused_self))]
241    pub(crate) fn for_each(&self, count: usize, job: &(dyn Fn(usize) + Sync)) {
242        #[cfg(not(target_arch = "wasm32"))]
243        if let Some(pool) = &self.pool {
244            use rayon::prelude::*;
245            pool.install(|| (0..count).into_par_iter().for_each(job));
246            return;
247        }
248        (0..count).for_each(job);
249    }
250
251    /// Calls `work(index)` in parallel for every index below `count`, collecting in index order.
252    #[cfg_attr(target_arch = "wasm32", allow(clippy::unused_self))]
253    pub(crate) fn map<T: Send>(
254        &self,
255        count: usize,
256        work: impl Fn(usize) -> T + Sync + Send,
257    ) -> Vec<T> {
258        #[cfg(not(target_arch = "wasm32"))]
259        if let Some(pool) = &self.pool {
260            use rayon::prelude::*;
261            return pool.install(|| (0..count).into_par_iter().map(&work).collect());
262        }
263        (0..count).map(work).collect()
264    }
265}
266
267/// Rows per band for an image `width` pixels wide.
268fn band_rows(width: usize) -> usize {
269    (BAND_PIXELS / width).clamp(1, 64)
270}
271
272impl crate::layout_pack::Bands for Workers {
273    fn rows_per_band(&self, _chroma_rows: usize, row_pixels: usize) -> usize {
274        self.band_rows(row_pixels)
275    }
276
277    fn run(&self, count: usize, job: &(dyn Fn(usize) + Sync)) {
278        self.for_each(count, job);
279    }
280}
281
282#[cfg(test)]
283mod tests {
284    use super::*;
285    use std::sync::Arc;
286    use std::sync::atomic::{AtomicUsize, Ordering};
287
288    #[test]
289    fn every_band_reports_progress_to_the_calling_threads_watcher_on_any_thread() {
290        let width = 512;
291        let rows = band_rows(width);
292        for threads in [1, 4] {
293            let workers = Workers::new(threads);
294            let reported = Arc::new(AtomicUsize::new(0));
295            let counter = Arc::clone(&reported);
296            let report = report_band_progress(Arc::new(move || {
297                counter.fetch_add(1, Ordering::Relaxed);
298            }));
299            let mut pixels = vec![0_u8; width * rows * 9];
300            workers.bands(&mut pixels, width, |_, chunk| chunk.fill(1));
301            workers.bands_with(&mut pixels, width, || (), |(), _, chunk| chunk.fill(2));
302            assert_eq!(reported.load(Ordering::Relaxed), 18, "{threads} threads");
303            drop(report);
304            workers.bands(&mut pixels, width, |_, chunk| chunk.fill(3));
305            assert_eq!(reported.load(Ordering::Relaxed), 18, "the report ended");
306        }
307    }
308}