oxedyne/fe2o3/fe2o3_austenite/src/eval/fixpoint.rs
8.1 KiB, 25 runs
created by r1870400018:63208, 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 | // U8 owns this file: the outer fixpoint. Evaluate once; then up to `MAX_PASSES` times stream the pages |
| 2 | // from the top against the previous introspector, recording each page's located elements as it passes |
| 3 | // and handing the page to the sink, stopping when every recorded read answers the same against the |
| 4 | // introspector the pass built. A fifth pass still moving is a warning and its output stands, as in Typst. |
| 5 | // |
| 6 | // Each pass starts clean: the locator, the read log, the context and the loop fuel are reset, and the |
| 7 | // diagnostics of the previous pass are dropped, so a `context` error a first pass makes for want of a |
| 8 | // later label is gone once the label is known. Only the final pass's errors fail the run. |
| 9 | // |
| 10 | // What fails a pass outright and what waits are Typst's own division. A show rule's error (a reference |
| 11 | // to a label the first pass has not seen above all) is delayed by `Engine::delay`: the element shows as |
| 12 | // nothing, the pass completes, and the error counts only if the final pass still holds it. An error from |
| 13 | // anywhere else, layout above all, ends the compile in the pass it occurs in. |
| 14 | // |
| 15 | // Streaming (addendum 2026-09-23): a pass holds one page at a time. Nothing here keeps a page, a frame or |
| 16 | // a run; what outlives a page is its records in the [`Builder`], and what outlives a pass is the |
| 17 | // [`Introspector`] built from them and the sink's own output. |
| 18 | |
| 19 | use crate::diag::{ |
| 20 | Diagnostic, |
| 21 | DiagnosticKind, |
| 22 | }; |
| 23 | use crate::eval::content::Content; |
| 24 | use crate::eval::intro::{ |
| 25 | self, |
| 26 | Builder, |
| 27 | Introspector, |
| 28 | ReadLog, |
| 29 | }; |
| 30 | use crate::eval::styles::StyleChain; |
| 31 | use crate::eval::value::{ |
| 32 | Module, |
| 33 | Value, |
| 34 | }; |
| 35 | use crate::eval::{ |
| 36 | Context, |
| 37 | Engine, |
| 38 | }; |
| 39 | use crate::flow; |
| 40 | use crate::page::Page; |
| 41 | use crate::syntax::Span; |
| 42 | use crate::timings::Phase; |
| 43 | |
| 44 | use oxedyne_fe2o3_core::prelude::*; |
| 45 | |
| 46 | use std::sync::Arc; |
| 47 | |
| 48 | pub const MAX_PASSES: u32 = 5; |
| 49 | |
| 50 | /// What a compilation laid out: the final introspector and the counts. The pages went to the sink. |
| 51 | #[derive(Clone, Debug)] |
| 52 | pub struct Laid { |
| 53 | pub intro: Arc<Introspector>, |
| 54 | pub pages: u32, |
| 55 | pub passes: u32, |
| 56 | pub converged: bool, |
| 57 | } |
| 58 | |
| 59 | /// Where a pass's pages go, one at a time. Every pass but the last is discarded, so a sink keeps what it |
| 60 | /// writes provisional until [`finish`](Self::finish), which runs once, after the pass that converged |
| 61 | /// (or the fifth), with that pass's introspector: the outline, the page tree and the ledger come from it. |
| 62 | pub trait PageSink { |
| 63 | /// Takes a finished page (placed and decorated) and drops it. |
| 64 | fn page(&mut self, engine: &mut Engine, page: Page) -> Outcome<()>; |
| 65 | /// Forgets the pass just ended: its output and its glyph sets. |
| 66 | fn discard_pass(&mut self) -> Outcome<()>; |
| 67 | fn finish(&mut self, engine: &mut Engine, intro: &Introspector) -> Outcome<()>; |
| 68 | } |
| 69 | |
| 70 | /// One pass over the document's content: its pages to the sink, its located elements to the builder. |
| 71 | /// Returns the number of pages. [`Pages`] is the document's; a test may lay out by other means. |
| 72 | pub trait Layouter { |
| 73 | fn lay<S: PageSink>( |
| 74 | &mut self, |
| 75 | engine: &mut Engine, |
| 76 | content: &Content, |
| 77 | styles: &StyleChain, |
| 78 | builder: &mut Builder, |
| 79 | sink: &mut S, |
| 80 | ) |
| 81 | -> Outcome<u32>; |
| 82 | } |
| 83 | |
| 84 | /// A pass's pages, one at a time: the document's are U6b's `flow::Paginator`, each body placed with its |
| 85 | /// furniture by `driver::place_page`, which records the page's located elements in the builder. |
| 86 | pub trait PageSource { |
| 87 | /// The next page, placed and decorated, with its `page.numbering`; `None` after the last page. |
| 88 | fn next_page(&mut self, engine: &mut Engine, builder: &mut Builder) -> Outcome<Option<(Page, Value)>>; |
| 89 | } |
| 90 | |
| 91 | /// The document layouter. |
| 92 | #[derive(Clone, Copy, Debug, Default)] |
| 93 | pub struct Pages; |
| 94 | |
| 95 | impl Layouter for Pages { |
| 96 | fn lay<S: PageSink>( |
| 97 | &mut self, |
| 98 | engine: &mut Engine, |
| 99 | content: &Content, |
| 100 | styles: &StyleChain, |
| 101 | builder: &mut Builder, |
| 102 | sink: &mut S, |
| 103 | ) |
| 104 | -> Outcome<u32> |
| 105 | { |
| 106 | place(engine, &mut flow::paginate(content, styles), builder, sink) |
| 107 | } |
| 108 | } |
| 109 | |
| 110 | // The paginator is the document's page source: the next page's furniture is laid out and its body placed on |
| 111 | // its page, which records the page's located elements in the builder. |
| 112 | impl PageSource for flow::Paginator { |
| 113 | fn next_page(&mut self, engine: &mut Engine, builder: &mut Builder) -> Outcome<Option<(Page, Value)>> { |
| 114 | match res!(self.next_placed(engine, builder)) { |
| 115 | None => Ok(None), |
| 116 | Some((page, setup)) => { |
| 117 | builder.document(res!(intro::document_info(&setup.styles))); |
| 118 | Ok(Some((page, setup.numbering.clone()))) |
| 119 | }, |
| 120 | } |
| 121 | } |
| 122 | } |
| 123 | |
| 124 | /// Streams one pass: each page from the source is counted with its numbering, then goes to the sink and |
| 125 | /// is dropped. Returns the number of pages. |
| 126 | pub fn place<P: PageSource, S: PageSink>( |
| 127 | engine: &mut Engine, |
| 128 | source: &mut P, |
| 129 | builder: &mut Builder, |
| 130 | sink: &mut S, |
| 131 | ) |
| 132 | -> Outcome<u32> |
| 133 | { |
| 134 | let mut n = 0; |
| 135 | while let Some((page, numbering)) = res!(source.next_page(engine, builder)) { |
| 136 | n += 1; |
| 137 | builder.page(page.number, &numbering); |
| 138 | res!(engine.timed(Phase::Sink, |engine| sink.page(engine, page))); |
| 139 | } |
| 140 | Ok(n) |
| 141 | } |
| 142 | |
| 143 | pub fn run<S: PageSink>(engine: &mut Engine, module: &Module, sink: &mut S) -> Outcome<Laid> { |
| 144 | run_with(engine, module, &mut Pages, sink) |
| 145 | } |
| 146 | |
| 147 | /// The fixpoint over any layouter. The first pass reads the engine's introspector as it stands, empty |
| 148 | /// for a fresh engine, so a caller holding a previous compilation's introspector starts warm. |
| 149 | pub fn run_with<L: Layouter, S: PageSink>( |
| 150 | engine: &mut Engine, |
| 151 | module: &Module, |
| 152 | layouter: &mut L, |
| 153 | sink: &mut S, |
| 154 | ) |
| 155 | -> Outcome<Laid> |
| 156 | { |
| 157 | let mark = engine.diags.len(); |
| 158 | let fuel = engine.fuel; |
| 159 | let styles = StyleChain::root(); |
| 160 | let mut passes = 0; |
| 161 | loop { |
| 162 | passes += 1; |
| 163 | engine.diags.truncate(mark); |
| 164 | engine.locator.reset(); |
| 165 | engine.reads = ReadLog::default(); |
| 166 | engine.context = Context::default(); |
| 167 | engine.fuel = fuel; |
| 168 | engine.body = None; |
| 169 | if let Some(t) = engine.timings.as_mut() { |
| 170 | t.begin_pass(); |
| 171 | } |
| 172 | let mut builder = Builder::new(); |
| 173 | let laid = layouter.lay(engine, &module.content, &styles, &mut builder, sink); |
| 174 | let pages = match laid { |
| 175 | Ok(n) => n, |
| 176 | Err(e) => { |
| 177 | res!(engine.timed(Phase::Sink, |_| sink.discard_pass())); |
| 178 | return Err(e); |
| 179 | } |
| 180 | }; |
| 181 | let (intro, converged) = res!(engine.timed(Phase::Settle, |engine| -> Outcome<_> { |
| 182 | let intro = Arc::new(builder.finish()); |
| 183 | let converged = res!(engine.reads.holds(&intro)); |
| 184 | Ok((intro, converged)) |
| 185 | })); |
| 186 | if !converged && passes < MAX_PASSES { |
| 187 | res!(engine.timed(Phase::Sink, |_| sink.discard_pass())); |
| 188 | engine.intro = intro; |
| 189 | continue; |
| 190 | } |
| 191 | if !converged { |
| 192 | res!(warn_unsettled(engine, &intro)); |
| 193 | } |
| 194 | engine.intro = intro.clone(); |
| 195 | dedupe_errors(&mut engine.diags, mark); |
| 196 | if let Some(d) = engine.diags[mark..].iter().find(|d| d.is_error()) { |
| 197 | let e = err!("{}", d.message; Input, Invalid); |
| 198 | res!(engine.timed(Phase::Sink, |_| sink.discard_pass())); |
| 199 | return Err(e); |
| 200 | } |
| 201 | res!(engine.timed(Phase::Finish, |engine| sink.finish(engine, &intro))); |
| 202 | return Ok(Laid { intro, pages, passes, converged }); |
| 203 | } |
| 204 | } |
| 205 | |
| 206 | /// Typst's `deduplicate`: an error met again at one span with one message is reported once. A body laid out |
| 207 | /// again, measured and then placed, shows its failed element each time. |
| 208 | fn dedupe_errors(diags: &mut Vec<Diagnostic>, mark: usize) { |
| 209 | let mut kept: Vec<Diagnostic> = Vec::with_capacity(diags.len() - mark); |
| 210 | for d in diags.drain(mark..) { |
| 211 | if d.is_error() && kept.iter().any(|k| k.is_error() && k.span == d.span && k.message == d.message) { |
| 212 | continue; |
| 213 | } |
| 214 | kept.push(d); |
| 215 | } |
| 216 | diags.extend(kept); |
| 217 | } |
| 218 | |
| 219 | /// Typst's non-convergence report: a summary, then one warning for each counter, state, query or |
| 220 | /// location that still moved. |
| 221 | fn warn_unsettled(engine: &mut Engine, intro: &Introspector) -> Outcome<()> { |
| 222 | let mut notes: Vec<String> = Vec::new(); |
| 223 | for r in res!(engine.reads.changed(intro)) { |
| 224 | let note = intro::describe(r, intro); |
| 225 | if !notes.contains(¬e) { |
| 226 | notes.push(note); |
| 227 | } |
| 228 | } |
| 229 | engine.diags.push(Diagnostic::warning(DiagnosticKind::Limit, Span::detached(), "document did not converge within five attempts") |
| 230 | .with_hint(fmt!("see {} additional warning{} for more details", notes.len(), |
| 231 | if notes.len() == 1 { "" } else { "s" })) |
| 232 | .with_hint("see https://typst.app/help/convergence for help")); |
| 233 | for n in notes { |
| 234 | engine.diags.push(Diagnostic::warning(DiagnosticKind::Limit, Span::detached(), n)); |
| 235 | } |
| 236 | Ok(()) |
| 237 | } |