Oregami
Repositories/oxedyne/fe2o3

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
19use crate::diag::{
20 Diagnostic,
21 DiagnosticKind,
22};
23use crate::eval::content::Content;
24use crate::eval::intro::{
25 self,
26 Builder,
27 Introspector,
28 ReadLog,
29};
30use crate::eval::styles::StyleChain;
31use crate::eval::value::{
32 Module,
33 Value,
34};
35use crate::eval::{
36 Context,
37 Engine,
38};
39use crate::flow;
40use crate::page::Page;
41use crate::syntax::Span;
42use crate::timings::Phase;
43
44use oxedyne_fe2o3_core::prelude::*;
45
46use std::sync::Arc;
47
48pub 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)]
52pub 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.
62pub 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.
72pub 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.
86pub 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)]
93pub struct Pages;
94
95impl 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.
112impl 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.
126pub 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
143pub 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.
149pub 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.
208fn 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.
221fn 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(&note) {
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}