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")] |
| 16 | use crate::eval::plugin::{ |
| 17 | Plugin, |
| 18 | PluginFunc, |
| 19 | }; |
| 20 | use crate::flow::par::ParMemo; |
| 21 | use crate::fonts::ShapeStats; |
| 22 | |
| 23 | use oxedyne_fe2o3_core::prelude::*; |
| 24 | use oxedyne_fe2o3_hash::fingerprint::Fingerprint; |
| 25 | use oxedyne_fe2o3_hash::fingerprint::Fingerprinter; |
| 26 | #[cfg(feature = "plugin")] |
| 27 | use oxedyne_fe2o3_data::gen_map::GenMap; |
| 28 | |
| 29 | #[cfg(feature = "plugin")] |
| 30 | use std::sync::Arc; |
| 31 | |
| 32 | pub const PAR_BUDGET: usize = 16 << 20; // bytes of laid paragraphs a session keeps by default |
| 33 | pub const SHAPE_BUDGET: usize = 32 << 20; // bytes of shaped runs a session keeps by default |
| 34 | pub 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. |
| 37 | const 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)] |
| 47 | pub 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 | |
| 53 | impl Default for Budgets { |
| 54 | fn default() -> Self { |
| 55 | Self { shapes: SHAPE_BUDGET, pars: PAR_BUDGET, ledger: 0 } |
| 56 | } |
| 57 | } |
| 58 | |
| 59 | impl 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 | |
| 79 | fn 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)] |
| 98 | pub 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. |
| 117 | pub 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)] |
| 136 | pub 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 | |
| 146 | impl 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)] |
| 202 | pub 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")] |
| 209 | impl 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")] |
| 220 | impl 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")] |
| 245 | fn 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")] |
| 258 | impl 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 | } |