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;