Oregami
Repositories/oxedyne/fe2o3

oxedyne/fe2o3/fe2o3_austenite/src/caches.rs

12.8 KiB, 47 runs

created by r1870400018:68809, which is this file's identity for as long as the history lasts, whatever it is later renamed to

download · who wrote it · its history

1//! The caches a [`Session`](crate::compile::Session) keeps from one compile to the next, and what scopes
2//! them.
3//!
4//! A cache here is keyed on content, so an entry made by a compile that went on to fail is as good as one
5//! from a compile that finished, and a hit never depends on which compile made the entry. What a content
6//! key cannot name is the configuration the compile ran under: the face set, `sys.inputs` and the engine.
7//! A compile folds those into one [`configuration`] fingerprint, and when it differs from the one the
8//! entries were made under every cache empties. Nothing is keyed across engines: the caches live in the
9//! session, and the engine's identity is in the fingerprint.
10//!
11//! The session lends its [`Caches`] to the [`Engine`](crate::eval::Engine) for the length of a compile and
12//! takes them back. The paragraph memo and the page ledger each add a [`GenMap`](oxedyne_fe2o3_data::gen_map::GenMap)
13//! here, stepped by [`Caches::begin`], swept by [`Caches::end`] and emptied by [`Caches::clear`].
14
15#[cfg(feature = "plugin")]
16use crate::eval::plugin::{
17 Plugin,
18 PluginFunc,
19};
20use crate::flow::par::ParMemo;
21use crate::fonts::ShapeStats;
22
23use oxedyne_fe2o3_core::prelude::*;
24use oxedyne_fe2o3_hash::fingerprint::Fingerprint;
25use oxedyne_fe2o3_hash::fingerprint::Fingerprinter;
26#[cfg(feature = "plugin")]
27use oxedyne_fe2o3_data::gen_map::GenMap;
28
29#[cfg(feature = "plugin")]
30use std::sync::Arc;
31
32pub const PAR_BUDGET: usize = 16 << 20; // bytes of laid paragraphs a session keeps by default
33pub const SHAPE_BUDGET: usize = 32 << 20; // bytes of shaped runs a session keeps by default
34pub const PLUGIN_BUDGET: usize = 64 << 20; // bytes of loaded plugins and their results a session keeps
35
36// The largest whole number JavaScript holds exactly.
37const JS_WHOLE: f64 = 9_007_199_254_740_991.0;
38
39// ┌───────────────────────────────────────────────────────────────────────────┐
40// │ BUDGETS │
41// └───────────────────────────────────────────────────────────────────────────┘
42
43/// The bytes each cache may hold, set by the host. The shaped-run cache at its budget evicts its least recently
44/// used result; a cache swept by generation refuses a new entry and loses none. A lower budget slows a compile
45/// and never changes what it makes.
46#[derive(Clone, Copy, Debug, PartialEq, Eq)]
47pub struct Budgets {
48 pub shapes: usize,
49 pub pars: usize,
50 pub ledger: usize, // the ledger's share is set with the ledger
51}
52
53impl Default for Budgets {
54 fn default() -> Self {
55 Self { shapes: SHAPE_BUDGET, pars: PAR_BUDGET, ledger: 0 }
56 }
57}
58
59impl Budgets {
60 /// These budgets with each of `shapes`, `pars` and `ledger` replaced by the number of bytes given, as a
61 /// host that counts in JavaScript numbers gives it; a field left `None` stands. A number that is not a
62 /// whole count of bytes this target can hold refuses the lot, naming the field, so a host never
63 /// half-applies a change.
64 pub fn with(self, shapes: Option<f64>, pars: Option<f64>, ledger: Option<f64>) -> Outcome<Self> {
65 let mut out = self;
66 for (name, given, slot) in [
67 ("shapes", shapes, &mut out.shapes),
68 ("pars", pars, &mut out.pars),
69 ("ledger", ledger, &mut out.ledger),
70 ] {
71 if let Some(n) = given {
72 *slot = res!(whole_bytes(name, n));
73 }
74 }
75 Ok(out)
76 }
77}
78
79fn whole_bytes(name: &str, n: f64) -> Outcome<usize> {
80 if !(n >= 0.0 && n.fract() == 0.0 && n <= JS_WHOLE) {
81 return Err(err!("The {} budget is {}, which is not a whole number of bytes.", name, n; Input, Invalid));
82 }
83 match usize::try_from(n as u64) {
84 Ok(b) => Ok(b),
85 Err(_) => Err(err!("The {} budget of {} bytes is more than this target can address.", name, n; Input, Invalid)),
86 }
87}
88
89// ┌───────────────────────────────────────────────────────────────────────────┐
90// │ COUNTERS │
91// └───────────────────────────────────────────────────────────────────────────┘
92
93/// What a compile's caches did, read off its result. Every paragraph laid counts as a hit or a miss of the
94/// paragraph memo, one that is not kept (it holds an inline box or equation) as a miss; the page counts are
95/// filled by the unit that owns the ledger and are zero until then; the shape stats are the shaped-run
96/// cache's, as the compile left it.
97#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
98pub struct Counters {
99 pub replayed: u64, // pages replayed from the ledger
100 pub relaid: u64, // pages laid again
101 pub par_hits: u64,
102 pub par_misses: u64,
103 pub plugin_hits: u64, // loads, transitions and calls answered from the memo
104 pub plugin_misses: u64, // and those run
105 pub shapes: ShapeStats,
106}
107
108// ┌───────────────────────────────────────────────────────────────────────────┐
109// │ CONFIGURATION │
110// └───────────────────────────────────────────────────────────────────────────┘
111
112/// The fingerprint of everything outside the source that decides what a compile makes: the face set
113/// (`faces`, [`FontBook::fingerprint`](crate::fonts::FontBook::fingerprint)), the `sys.inputs` pairs, and
114/// the engine, by the commit it was built from. The inputs go in as given, since their order is the order of
115/// the dictionary a document reads; [`Session::set_inputs`](crate::compile::Session::set_inputs) has already
116/// folded a repeated key.
117pub fn configuration(faces: Fingerprint, inputs: &[(String, String)], engine: &str) -> Fingerprint {
118 let mut f = Fingerprinter::new();
119 f.write_fingerprint(faces);
120 f.write_usize(inputs.len());
121 for (key, val) in inputs {
122 f.write_str(key);
123 f.write_str(val);
124 }
125 f.write_str(engine);
126 f.finish()
127}
128
129// ┌───────────────────────────────────────────────────────────────────────────┐
130// │ CACHES │
131// └───────────────────────────────────────────────────────────────────────────┘
132
133/// The session's caches. Its entries (the paragraph memo, and the page ledger when it comes) are all scoped by
134/// one configuration fingerprint and swept by generation.
135#[derive(Debug, Default)]
136pub struct Caches {
137 pub budgets: Budgets,
138 pub counters: Counters, // this compile's
139 pub pars: ParMemo, // the paragraphs broken into lines
140 #[cfg(feature = "plugin")]
141 pub plugins: PluginMemo, // plugins loaded and transitioned, and their calls' results
142 config: Option<Fingerprint>, // what the entries were made under, none before the first compile
143 resets: u64, // how many times a changed configuration emptied them
144}
145
146impl Caches {
147 pub fn new(budgets: Budgets) -> Self {
148 Self { budgets, ..Self::default() }
149 }
150
151 /// Opens a compile under `config`: the counters start from zero, every cache's generation steps, and a
152 /// configuration that is not the one the entries were made under empties them first. Answers whether
153 /// it emptied them. The first compile has no entries to empty and does not count as a reset.
154 pub fn begin(&mut self, config: Fingerprint) -> bool {
155 let moved = match self.config {
156 Some(held) => held != config,
157 None => false,
158 };
159 if moved {
160 self.clear();
161 self.resets += 1;
162 }
163 self.config = Some(config);
164 self.counters = Counters::default();
165 self.pars.begin(self.budgets.pars);
166 #[cfg(feature = "plugin")]
167 self.plugins.begin();
168 moved
169 }
170
171 /// Closes the compile: each cache drops what neither this compile nor the one before touched.
172 pub fn end(&mut self) {
173 self.pars.sweep();
174 #[cfg(feature = "plugin")]
175 self.plugins.sweep();
176 }
177
178 /// Empties every cache. A panic, which leaves entries of unknown worth, drops the whole session instead.
179 pub fn clear(&mut self) {
180 self.pars.clear();
181 #[cfg(feature = "plugin")]
182 self.plugins.clear();
183 }
184
185 /// The configuration the entries were made under.
186 pub fn config(&self) -> Option<Fingerprint> { self.config }
187
188 /// How many times a changed configuration has emptied the caches.
189 pub fn resets(&self) -> u64 { self.resets }
190}
191
192// ┌───────────────────────────────────────────────────────────────────────────┐
193// │ PLUGINS │
194// └───────────────────────────────────────────────────────────────────────────┘
195
196/// Plugins memoised as Typst memoises them: a load by the module's bytes, and a call or a transition by the
197/// function's fingerprint, which names the module, the transitions its plugin came through (FIX-9) and the
198/// function, together with the bytes of every argument. A plugin is deterministic, so a hit is the answer
199/// the call would give. Failures are not kept; they run again, under the same limits.
200#[cfg(feature = "plugin")]
201#[derive(Debug)]
202pub struct PluginMemo {
203 loads: GenMap<Fingerprint, Arc<Plugin>>,
204 steps: GenMap<Fingerprint, Arc<Plugin>>, // transitions
205 calls: GenMap<Fingerprint, Arc<Vec<u8>>>,
206}
207
208#[cfg(feature = "plugin")]
209impl Default for PluginMemo {
210 fn default() -> Self {
211 Self {
212 loads: GenMap::new(PLUGIN_BUDGET),
213 steps: GenMap::new(PLUGIN_BUDGET),
214 calls: GenMap::new(PLUGIN_BUDGET),
215 }
216 }
217}
218
219#[cfg(feature = "plugin")]
220impl PluginMemo {
221 fn begin(&mut self) {
222 self.loads.begin();
223 self.steps.begin();
224 self.calls.begin();
225 }
226
227 fn sweep(&mut self) {
228 self.loads.sweep();
229 self.steps.sweep();
230 self.calls.sweep();
231 }
232
233 fn clear(&mut self) {
234 self.loads.clear();
235 self.steps.clear();
236 self.calls.clear();
237 }
238
239 /// The entries held: loads, transitions and calls.
240 pub fn len(&self) -> (usize, usize, usize) { (self.loads.len(), self.steps.len(), self.calls.len()) }
241}
242
243// A call or transition: the function, then each argument's length and bytes.
244#[cfg(feature = "plugin")]
245fn plugin_key(tag: u8, f: &PluginFunc, args: &[Arc<Vec<u8>>]) -> Fingerprint {
246 let mut h = Fingerprinter::new();
247 h.write_u8(tag);
248 h.write_fingerprint(f.fingerprint());
249 h.write_usize(args.len());
250 for a in args {
251 h.write_usize(a.len());
252 h.write_fingerprint(Fingerprint::of(a));
253 }
254 h.finish()
255}
256
257#[cfg(feature = "plugin")]
258impl Caches {
259 /// `plugin(source)`, memoised on the module's bytes.
260 pub fn plugin_load(&mut self, bytes: &[u8], fuel: u64) -> Outcome<Arc<Plugin>> {
261 let key = Fingerprint::of(bytes);
262 if let Some(p) = self.plugins.loads.get(&key) {
263 self.counters.plugin_hits += 1;
264 return Ok(p.clone());
265 }
266 self.counters.plugin_misses += 1;
267 let p = Arc::new(res!(Plugin::load(bytes, fuel)));
268 let size = p.size();
269 self.plugins.loads.insert(key, p.clone(), size);
270 Ok(p)
271 }
272
273 /// `plugin.transition(f, ..args)`, memoised on the function and the arguments' bytes.
274 pub fn plugin_transition(&mut self, f: &PluginFunc, args: Vec<Arc<Vec<u8>>>, fuel: u64)
275 -> Outcome<Arc<Plugin>>
276 {
277 let key = plugin_key(b't', f, &args);
278 if let Some(p) = self.plugins.steps.get(&key) {
279 self.counters.plugin_hits += 1;
280 return Ok(p.clone());
281 }
282 self.counters.plugin_misses += 1;
283 let p = Arc::new(res!(f.transition(args, fuel)));
284 let size = p.size();
285 self.plugins.steps.insert(key, p.clone(), size);
286 Ok(p)
287 }
288
289 /// `f(..args)` for a plugin function, memoised on the function and the arguments' bytes.
290 pub fn plugin_call(&mut self, f: &PluginFunc, args: Vec<Arc<Vec<u8>>>, fuel: u64)
291 -> Outcome<Arc<Vec<u8>>>
292 {
293 let key = plugin_key(b'c', f, &args);
294 if let Some(out) = self.plugins.calls.get(&key) {
295 self.counters.plugin_hits += 1;
296 return Ok(out.clone());
297 }
298 self.counters.plugin_misses += 1;
299 let out = Arc::new(res!(f.call(args, fuel)));
300 self.plugins.calls.insert(key, out.clone(), out.len() + std::mem::size_of::<Vec<u8>>());
301 Ok(out)
302 }
303}