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    /// Apply `f` to every item, in parallel where the budget allows.
80    ///
81    /// Without the `parallel-encode` feature this is `items.iter().map(f)`
82    /// and nothing is spawned, so callers need no second code path.
83    ///
84    /// Results come back in the order of `items` however the work was
85    /// scheduled, so nothing a caller decides from them -- which codec was
86    /// smallest, which entry goes where in a manifest -- can depend on how
87    /// many threads the build machine happened to offer.
88    ///
89    /// Items are claimed one at a time rather than dealt out up front:
90    /// assets differ in size by orders of magnitude, and a static split
91    /// leaves one worker holding the only large file while the rest idle.
92    ///
93    /// # Panics
94    ///
95    /// Propagates a panic from `f` once the other workers have stopped,
96    /// which is the same outcome the sequential form gives and the one a
97    /// proc macro wants: an encoder that panicked has no partial result
98    /// worth keeping.
99    pub fn map<T, R, F>(items: &[T], f: F) -> Vec<R>
100    where
101        T: Sync,
102        R: Send,
103        F: Fn(&T) -> R + Sync,
104    {
105        let len = items.len();
106        let extra = if len < 2 { 0 } else { reserve(len - 1) };
107        if extra == 0 {
108            return items.iter().map(f).collect();
109        }
110
111        let next = AtomicUsize::new(0);
112        let (tx, rx) = mpsc::channel();
113        std::thread::scope(|scope| {
114            for _ in 0..extra {
115                let tx = tx.clone();
116                let (next, f) = (&next, &f);
117                scope.spawn(move || {
118                    while let Some(index) = claim(next, len) {
119                        // The receiver outlives the scope, so a send here
120                        // cannot fail.
121                        let _ = tx.send((index, f(&items[index])));
122                    }
123                });
124            }
125            // The calling thread is one of the workers, not an idle
126            // supervisor; its own sender has to go before the channel can
127            // close.
128            while let Some(index) = claim(&next, len) {
129                let _ = tx.send((index, f(&items[index])));
130            }
131            drop(tx);
132        });
133        spare().fetch_add(extra, Ordering::Relaxed);
134
135        let mut slots: Vec<Option<R>> = (0..len).map(|_| None).collect();
136        for (index, value) in rx {
137            slots[index] = Some(value);
138        }
139        slots
140            .into_iter()
141            .map(|slot| slot.expect("every index was claimed exactly once"))
142            .collect()
143    }
144}
145
146#[cfg(not(all(feature = "enc", feature = "parallel-encode")))]
147mod imp {
148    use alloc::vec::Vec;
149
150    /// Apply `f` to every item, in order.
151    ///
152    /// The shape the `parallel-encode` build offers, without the feature:
153    /// callers are written once and get whichever this build compiled.
154    pub fn map<T, R, F>(items: &[T], f: F) -> Vec<R>
155    where
156        T: Sync,
157        R: Send,
158        F: Fn(&T) -> R + Sync,
159    {
160        items.iter().map(f).collect()
161    }
162}
163
164pub use imp::map;