Skip to main content

embark_codec/
parallel.rs

1//! The build-time encoder's thread budget.
2//!
3//! Public because the proc macro sits above the codecs and has its own
4//! independent work -- one derive compresses every file in a folder -- and
5//! the budget only bounds the machine if all three levels draw on the same
6//! one. Nothing here is reachable from `dec`.
7//!
8//! Compression runs once, on the machine doing the build, inside a proc
9//! macro. Decompression runs in every consumer's shipped binary, and never
10//! reaches this module. So the encoder is free to use every core the build
11//! machine has, and the only real question is how to divide them between
12//! work that nests: one derive compresses many files, each file may try
13//! several codecs, and one codec may split its input into blocks.
14//!
15//! A single budget answers that. Each level asks for as many extra workers
16//! as it has independent work, takes whatever is left, and hands them back
17//! when it is done, so the three levels together never oversubscribe.
18
19#[cfg(all(feature = "enc", feature = "parallel-encode"))]
20mod imp {
21    extern crate std;
22
23    use alloc::vec::Vec;
24    use core::sync::atomic::{AtomicUsize, Ordering};
25    use std::sync::{OnceLock, mpsc};
26
27    /// Threads the encoder may use in total, the calling thread included.
28    ///
29    /// `EMBARK_ENCODE_THREADS` overrides the machine's parallelism, which is
30    /// what a build under an external job server needs: cargo already runs
31    /// several rustc processes, and each one of them expanding a macro that
32    /// grabs every core is how a build machine ends up thrashing. Setting it
33    /// to `1` turns the encoder back into a single-threaded one.
34    fn workers() -> usize {
35        static WORKERS: OnceLock<usize> = OnceLock::new();
36        *WORKERS.get_or_init(|| {
37            let asked = std::env::var("EMBARK_ENCODE_THREADS")
38                .ok()
39                .and_then(|v| v.trim().parse::<usize>().ok());
40            match asked {
41                Some(n) if n > 0 => n,
42                _ => std::thread::available_parallelism().map_or(1, |n| n.get()),
43            }
44        })
45    }
46
47    /// Workers not currently claimed by an outer level.
48    fn spare() -> &'static AtomicUsize {
49        static SPARE: OnceLock<AtomicUsize> = OnceLock::new();
50        SPARE.get_or_init(|| AtomicUsize::new(workers() - 1))
51    }
52
53    /// Claim up to `want` extra workers, returning how many were granted.
54    fn reserve(want: usize) -> usize {
55        let spare = spare();
56        let mut free = spare.load(Ordering::Relaxed);
57        loop {
58            let take = want.min(free);
59            if take == 0 {
60                return 0;
61            }
62            match spare.compare_exchange_weak(
63                free,
64                free - take,
65                Ordering::Relaxed,
66                Ordering::Relaxed,
67            ) {
68                Ok(_) => return take,
69                Err(now) => free = now,
70            }
71        }
72    }
73
74    fn claim(next: &AtomicUsize, len: usize) -> Option<usize> {
75        let index = next.fetch_add(1, Ordering::Relaxed);
76        (index < len).then_some(index)
77    }
78
79    /// Workers on loan from the budget, handed back when this drops -- on
80    /// the way out of a panic as much as on the way out of `map`, so a
81    /// caller that catches one does not find the budget short forever.
82    struct Loan(usize);
83
84    impl Drop for Loan {
85        fn drop(&mut self) {
86            spare().fetch_add(self.0, Ordering::Relaxed);
87        }
88    }
89
90    /// Apply `f` to every item, in parallel where the budget allows.
91    ///
92    /// Without the `parallel-encode` feature this is `items.iter().map(f)`
93    /// and nothing is spawned, so callers need no second code path.
94    ///
95    /// Results come back in the order of `items` however the work was
96    /// scheduled, so nothing a caller decides from them -- which codec was
97    /// smallest, which entry goes where in a manifest -- can depend on how
98    /// many threads the build machine happened to offer.
99    ///
100    /// Items are claimed one at a time rather than dealt out up front:
101    /// assets differ in size by orders of magnitude, and a static split
102    /// leaves one worker holding the only large file while the rest idle.
103    ///
104    /// # Panics
105    ///
106    /// Propagates a panic from `f` once the other workers have stopped,
107    /// which is the same outcome the sequential form gives and the one a
108    /// proc macro wants: an encoder that panicked has no partial result
109    /// worth keeping.
110    pub fn map<T, R, F>(items: &[T], f: F) -> Vec<R>
111    where
112        T: Sync,
113        R: Send,
114        F: Fn(&T) -> R + Sync,
115    {
116        let len = items.len();
117        let extra = if len < 2 { 0 } else { reserve(len - 1) };
118        if extra == 0 {
119            return items.iter().map(f).collect();
120        }
121        let loan = Loan(extra);
122
123        let next = AtomicUsize::new(0);
124        let (tx, rx) = mpsc::channel();
125        std::thread::scope(|scope| {
126            for _ in 0..extra {
127                let tx = tx.clone();
128                let (next, f) = (&next, &f);
129                scope.spawn(move || {
130                    while let Some(index) = claim(next, len) {
131                        // The receiver outlives the scope, so a send here
132                        // cannot fail.
133                        let _ = tx.send((index, f(&items[index])));
134                    }
135                });
136            }
137            // The calling thread is one of the workers, not an idle
138            // supervisor; its own sender has to go before the channel can
139            // close.
140            while let Some(index) = claim(&next, len) {
141                let _ = tx.send((index, f(&items[index])));
142            }
143            drop(tx);
144        });
145        drop(loan);
146
147        let mut slots: Vec<Option<R>> = (0..len).map(|_| None).collect();
148        for (index, value) in rx {
149            slots[index] = Some(value);
150        }
151        slots
152            .into_iter()
153            .map(|slot| slot.expect("every index was claimed exactly once"))
154            .collect()
155    }
156}
157
158#[cfg(not(all(feature = "enc", feature = "parallel-encode")))]
159mod imp {
160    use alloc::vec::Vec;
161
162    /// Apply `f` to every item, in order.
163    ///
164    /// The shape the `parallel-encode` build offers, without the feature:
165    /// callers are written once and get whichever this build compiled.
166    pub fn map<T, R, F>(items: &[T], f: F) -> Vec<R>
167    where
168        T: Sync,
169        R: Send,
170        F: Fn(&T) -> R + Sync,
171    {
172        items.iter().map(f).collect()
173    }
174}
175
176pub use imp::map;