Skip to main content

raf_source/parse/
parallel.rs

1// SPDX-FileCopyrightText: 2026 Blackcat InformaticsĀ® Inc. <paudley@blackcatinformatics.ca>
2// SPDX-License-Identifier: MIT OR Apache-2.0 OR MulanPSL-2.0
3
4//! Coordinator-owned speculation; native syntax never leaves its fresh worker.
5
6use super::{
7    Candidate, ConfigurationKey, Extracted as Parsed, ExtractionGrant, PARSE_STACK_BYTES, Parser,
8    PreparedSource, extract_head, parse_syntax, storage,
9};
10use crate::{
11    ActiveConfiguration, DiskTree, FileId, LoadError, LoadErrorKind, LoadOptions, LockedBinding,
12    MemoryTree, Opened, RelPath, SourceAuthorityId, Tree, TreeError,
13};
14#[cfg(test)]
15use purrdf_lex::allocation::Shared;
16use purrdf_lex::allocation::{Admission, Ceiling, Memory, OwnedAdmission, StorageError};
17use std::alloc::Layout;
18use std::cell::RefCell;
19use std::error::Error;
20use std::fmt;
21use std::num::NonZeroUsize;
22use std::panic::{self, AssertUnwindSafe};
23use std::sync::{Condvar, Mutex};
24use std::thread::{Scope, ScopedJoinHandle};
25
26#[cfg(test)]
27pub(crate) mod tests;
28
29/// An explicitly selected Tree capability for native parallel parsing.
30///
31/// During a parallel load, observations must be stable and independent of call
32/// order, including file identities, listings and operation failures. Returned
33/// values, transitive opaque error sources and panic payloads exposed to read-ahead
34/// must have normal nonpanicking destruction, without depending on speculative
35/// disposal or panic-hook effects. These are behavioral eligibility conditions,
36/// not an unsafe marker or an immutable-filesystem claim. Stateful observation
37/// contracts retain the serial API.
38/// The coordinator performs all Tree access; no worker receives this object.
39pub trait ParallelTree: Tree + Sync {}
40
41impl ParallelTree for MemoryTree {}
42impl ParallelTree for DiskTree {}
43
44/// Independent scheduler ownership limits; source/index options remain unchanged.
45#[derive(Debug, Clone, PartialEq, Eq)]
46pub struct ParallelOptions {
47    workers: NonZeroUsize,
48    max_speculative_bytes: usize,
49}
50
51/// Invalid worker-stack arithmetic or insufficient fixed scheduler ownership.
52#[derive(Debug, Clone, Copy, PartialEq, Eq)]
53pub enum ParallelOptionsError {
54    /// The requested stack or scheduler layout cannot be represented.
55    SizeOverflow,
56    /// The ownership grant cannot hold the fixed job and synchronization slots.
57    SchedulerStorage {
58        /// Required bytes for the fixed scheduler layouts.
59        required: usize,
60        /// Caller-selected ownership ceiling.
61        maximum: usize,
62    },
63}
64
65impl fmt::Display for ParallelOptionsError {
66    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
67        match self {
68            Self::SizeOverflow => f.write_str("parallel worker stack or scheduler size overflows"),
69            Self::SchedulerStorage { required, maximum } => write!(
70                f,
71                "parallel scheduler requires {required} bytes, exceeding {maximum}; increase the speculative ownership grant or reduce workers"
72            ),
73        }
74    }
75}
76impl Error for ParallelOptionsError {}
77
78fn fixed_bytes(workers: usize) -> Result<usize, ParallelOptionsError> {
79    workers
80        .checked_mul(PARSE_STACK_BYTES)
81        .ok_or(ParallelOptionsError::SizeOverflow)?;
82    let controls =
83        Layout::array::<Control>(workers).map_err(|_| ParallelOptionsError::SizeOverflow)?;
84    let tasks = Layout::array::<Option<Task<'static>>>(workers)
85        .map_err(|_| ParallelOptionsError::SizeOverflow)?;
86    let inputs = Layout::array::<WorkerInput<'static>>(workers)
87        .map_err(|_| ParallelOptionsError::SizeOverflow)?;
88    controls
89        .size()
90        .checked_add(tasks.size())
91        .and_then(|bytes| bytes.checked_add(inputs.size()))
92        .ok_or(ParallelOptionsError::SizeOverflow)
93}
94
95impl ParallelOptions {
96    /// Validate an explicit worker count and additional scheduler/input grant.
97    ///
98    /// Native AST, parser TLS, runtime internals, original backend-returned
99    /// failure payloads (including path/name buffers), opaque panic payloads and
100    /// worker stacks are not covered by this byte grant. Scheduler-created
101    /// copies and carriers remain admitted. Stacks reserve 64 MiB per worker
102    /// separately.
103    ///
104    /// # Errors
105    /// Refuses unrepresentable layouts or a grant below the fixed slot layouts.
106    pub fn new(
107        workers: NonZeroUsize,
108        max_speculative_bytes: usize,
109    ) -> Result<Self, ParallelOptionsError> {
110        let required = fixed_bytes(workers.get())?;
111        if required > max_speculative_bytes {
112            return Err(ParallelOptionsError::SchedulerStorage {
113                required,
114                maximum: max_speculative_bytes,
115            });
116        }
117        Ok(Self {
118            workers,
119            max_speculative_bytes,
120        })
121    }
122}
123
124impl Default for ParallelOptions {
125    fn default() -> Self {
126        // Two fixed control/job slots fit in this constant grant on the primary
127        // native target; the constructor remains the single validation path.
128        Self::new(
129            NonZeroUsize::new(2).expect("two is nonzero"),
130            16 * 1024 * 1024,
131        )
132        .expect("two scheduler slots fit in the default ownership grant")
133    }
134}
135
136/// Scheduler high-water counts, finalized only after every worker has joined.
137///
138/// These counts exclude complete native AST/TLS/runtime allocations and do not
139/// change semantic [`crate::Usage`] or workspace structural equality.
140#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
141pub struct ParallelUsage {
142    /// Most simultaneously admitted jobs, including retained completed outcomes.
143    pub peak_live_jobs: usize,
144    /// Most requested scheduler and speculative ownership bytes admitted.
145    pub peak_scheduler_bytes: usize,
146    /// Most requested stack bytes for started workers not yet joined.
147    pub peak_worker_stack_bytes: usize,
148}
149
150#[derive(Default)]
151enum Grant {
152    #[default]
153    Pending,
154    Extract(HeadGrant),
155    Cancel,
156}
157
158struct HeadGrant {
159    path: RelPath,
160    extraction: ExtractionGrant,
161}
162
163#[derive(Default)]
164struct Control {
165    grant: Mutex<Grant>,
166    changed: Condvar,
167}
168
169/// The worker closure captures this one value by ownership. Its layout is
170/// admitted once per fixed slot; no separately allocated thread name is used.
171struct WorkerInput<'a> {
172    file: RelPath,
173    text: String,
174    scan: crate::prescan::Scan,
175    control: &'a Control,
176    configurations: Option<(&'a LoadOptions, ExtractionConfigurations<'a>)>,
177    #[cfg(test)]
178    probe: Option<Shared<tests::Probe>>,
179}
180
181#[derive(Clone, Copy)]
182pub(crate) enum ExtractionConfigurations<'a> {
183    Selected(&'a ActiveConfiguration),
184    Locked(&'a [LockedBinding]),
185}
186
187impl<'a> ExtractionConfigurations<'a> {
188    fn get(self, key: ConfigurationKey) -> Option<&'a ActiveConfiguration> {
189        match (self, key) {
190            (Self::Selected(active), ConfigurationKey::Selected) => Some(active),
191            (Self::Locked(bindings), ConfigurationKey::Locked(package, ordinal)) => bindings
192                .get(package.index())?
193                .configurations()
194                .get(ordinal.0),
195            _ => None,
196        }
197    }
198}
199
200impl WorkerInput<'_> {
201    fn run(self) -> Result<Option<Parsed>, LoadError> {
202        #[cfg(test)]
203        let _probe = tests::install(self.probe.clone());
204        super::entry::claim_registry(&self.file)?;
205        let syntax = parse_syntax(&self.file, &self.text);
206        #[cfg(test)]
207        tests::parsed(&self.file);
208        let Some(grant) = self.control.wait() else {
209            return syntax.map(|_| None);
210        };
211        let mut tree = syntax?;
212        #[cfg(test)]
213        tests::extracting(&grant.path);
214        let context = grant
215            .extraction
216            .configuration
217            .map(|key| {
218                self.configurations
219                    .and_then(|(options, configurations)| {
220                        configurations
221                            .get(key)
222                            .map(|active| (active, options, grant.extraction.usage))
223                    })
224                    .ok_or_else(|| {
225                        LoadError::new(
226                            &grant.path,
227                            None,
228                            LoadErrorKind::Internal {
229                                what: "parser grant carried an unavailable target configuration"
230                                    .into(),
231                            },
232                        )
233                    })
234            })
235            .transpose()?;
236        let head = extract_head(
237            &mut tree,
238            &grant.path,
239            &self.text,
240            grant.extraction.allowance,
241            context,
242        );
243        drop(tree);
244        Ok(Some(Parsed {
245            text: self.text,
246            head,
247            scan: self.scan,
248        }))
249    }
250}
251
252impl Control {
253    fn set(&self, grant: Grant) {
254        // No parser or caller code executes while this control lock is held.
255        *self
256            .grant
257            .lock()
258            .expect("fixed parser control operations do not panic") = grant;
259        self.changed.notify_one();
260    }
261
262    fn wait(&self) -> Option<HeadGrant> {
263        // Only fixed state assignments occur under this lock.
264        let mut grant = self
265            .grant
266            .lock()
267            .expect("fixed parser control operations do not panic");
268        loop {
269            match std::mem::take(&mut *grant) {
270                Grant::Extract(allowance) => return Some(allowance),
271                Grant::Cancel => return None,
272                Grant::Pending => {
273                    grant = self
274                        .changed
275                        .wait(grant)
276                        .expect("fixed parser control operations do not panic");
277                }
278            }
279        }
280    }
281
282    fn cancel(&self) {
283        // During unwinding recover only to release a parked worker; no poisoned
284        // state is accepted as a successful parsing outcome.
285        let mut grant = match self.grant.lock() {
286            Ok(grant) => grant,
287            Err(poison) => poison.into_inner(),
288        };
289        *grant = Grant::Cancel;
290        self.changed.notify_one();
291    }
292}
293
294struct Account {
295    bytes: usize,
296    peak: usize,
297    admission: OwnedAdmission<Ceiling>,
298}
299
300/// One candidate's subview of the original scheduler admission account.
301struct PreparationAdmission<'a> {
302    account: &'a RefCell<Account>,
303    bytes: usize,
304}
305
306impl Admission for PreparationAdmission<'_> {
307    fn resize(&mut self, bytes: usize) -> Result<(), StorageError> {
308        self.account.borrow_mut().with_memory(|memory| {
309            if bytes >= self.bytes {
310                memory.add_bytes(bytes - self.bytes)
311            } else {
312                memory.release_bytes(self.bytes - bytes)
313            }
314        })?;
315        self.bytes = bytes;
316        Ok(())
317    }
318}
319
320struct PreparedCandidate<'a> {
321    path: RelPath,
322    admission: OwnedAdmission<PreparationAdmission<'a>>,
323}
324
325impl Account {
326    fn with_memory<T>(
327        &mut self,
328        operation: impl FnOnce(&mut Memory<'_, OwnedAdmission<Ceiling>>) -> T,
329    ) -> T {
330        let mut memory = Memory::resume(&mut self.admission, self.bytes);
331        let result = operation(&mut memory);
332        self.bytes = memory.admitted_bytes();
333        // All allocations use fresh fixed buffers or a single checked add;
334        // no operation grows a previously allocated buffer under this account.
335        self.peak = self.peak.max(self.bytes);
336        result
337    }
338}
339
340pub(crate) struct Resources {
341    controls: Vec<Control>,
342    // Controls die before their original admission guard. Executor borrows keep
343    // this same account alive until every task has been destroyed and joined.
344    account: RefCell<Account>,
345    #[cfg(test)]
346    probe: Option<Shared<tests::Probe>>,
347}
348impl Resources {
349    pub(crate) fn new(options: &ParallelOptions) -> Result<Self, LoadError> {
350        let mut admission = OwnedAdmission::new(Ceiling(options.max_speculative_bytes));
351        let mut controls = Vec::new();
352        let mut memory = Memory::new(&mut admission);
353        memory
354            .reserve(&mut controls, options.workers.get())
355            .map_err(|cause| storage(&RelPath::root(), cause))?;
356        let inputs = Layout::array::<WorkerInput<'_>>(options.workers.get())
357            .map_err(|_| storage(&RelPath::root(), StorageError::SizeOverflow))?;
358        memory
359            .add_bytes(inputs.size())
360            .map_err(|cause| storage(&RelPath::root(), cause))?;
361        let bytes = memory.admitted_bytes();
362        controls.resize_with(options.workers.get(), Control::default);
363        Ok(Self {
364            controls,
365            account: RefCell::new(Account {
366                bytes,
367                peak: bytes,
368                admission,
369            }),
370            #[cfg(test)]
371            probe: tests::current(),
372        })
373    }
374}
375
376enum Running<'scope> {
377    Worker(ScopedJoinHandle<'scope, Result<Option<Parsed>, LoadError>>),
378    Failed(LoadError),
379    Joined(std::thread::Result<Result<Option<Parsed>, LoadError>>),
380    TreeFailed(TreeError),
381    Panicked(Box<dyn std::any::Any + Send>),
382    Empty,
383}
384
385struct Task<'scope> {
386    path: RelPath,
387    id: Option<FileId>,
388    running: Running<'scope>,
389    bytes: usize,
390    // Final candidate storage retains its original guard through payload drop.
391    _path_admission: Option<OwnedAdmission<PreparationAdmission<'scope>>>,
392}
393
394struct State<'scope> {
395    tasks: Vec<Option<Task<'scope>>>,
396    live_jobs: usize,
397    stack_bytes: usize,
398    usage: ParallelUsage,
399}
400
401pub(crate) struct Executor<'scope, 'env> {
402    scope: &'scope Scope<'scope, 'env>,
403    controls: &'scope [Control],
404    account: &'scope RefCell<Account>,
405    configurations: Option<(&'scope LoadOptions, ExtractionConfigurations<'scope>)>,
406    state: RefCell<State<'scope>>,
407    #[cfg(test)]
408    probe: Option<Shared<tests::Probe>>,
409}
410
411impl<'scope, 'env> Executor<'scope, 'env> {
412    pub(crate) fn new(
413        scope: &'scope Scope<'scope, 'env>,
414        resources: &'scope Resources,
415        options: &ParallelOptions,
416        configurations: Option<(&'scope LoadOptions, ExtractionConfigurations<'scope>)>,
417    ) -> Result<Self, LoadError> {
418        let mut tasks = Vec::new();
419        resources
420            .account
421            .borrow_mut()
422            .with_memory(|memory| memory.reserve(&mut tasks, options.workers.get()))
423            .map_err(|cause| storage(&RelPath::root(), cause))?;
424        tasks.resize_with(options.workers.get(), || None);
425        Ok(Self {
426            scope,
427            controls: &resources.controls,
428            account: &resources.account,
429            configurations,
430            state: RefCell::new(State {
431                tasks,
432                live_jobs: 0,
433                stack_bytes: 0,
434                usage: ParallelUsage::default(),
435            }),
436            #[cfg(test)]
437            probe: resources.probe.clone(),
438        })
439    }
440
441    /// Destroy all remaining jobs and slots before reporting a successful load.
442    pub(crate) fn finish(self) -> ParallelUsage {
443        self.cleanup();
444        let mut usage = self.state.borrow().usage;
445        usage.peak_scheduler_bytes = self.account.borrow().peak;
446        usage
447    }
448
449    fn admitted(state: &mut State<'scope>, task: &Task<'scope>) {
450        state.live_jobs = state
451            .live_jobs
452            .checked_add(1)
453            .expect("admitted jobs fit the fixed slot count");
454        state.usage.peak_live_jobs = state.usage.peak_live_jobs.max(state.live_jobs);
455        if matches!(task.running, Running::Worker(_)) {
456            state.stack_bytes = state
457                .stack_bytes
458                .checked_add(PARSE_STACK_BYTES)
459                .expect("worker stack total was validated before loading");
460            state.usage.peak_worker_stack_bytes =
461                state.usage.peak_worker_stack_bytes.max(state.stack_bytes);
462        }
463    }
464
465    fn joined(state: &mut State<'scope>) {
466        state.stack_bytes = state
467            .stack_bytes
468            .checked_sub(PARSE_STACK_BYTES)
469            .expect("joined worker retains its requested stack charge");
470    }
471
472    fn cleanup(&self) {
473        let mut state = self.state.borrow_mut();
474        // Cancellation has no user callbacks. Join every worker into its fixed
475        // slot before dropping any opaque error or panic payload.
476        for (slot, task) in state.tasks.iter().enumerate() {
477            if task.is_some() {
478                self.controls[slot].cancel();
479            }
480        }
481        for slot in 0..state.tasks.len() {
482            let Some(task) = state.tasks[slot].as_mut() else {
483                continue;
484            };
485            if matches!(task.running, Running::Worker(_)) {
486                let Running::Worker(worker) = std::mem::replace(&mut task.running, Running::Empty)
487                else {
488                    unreachable!("the selected running task is a worker");
489                };
490                task.running = Running::Joined(worker.join());
491                Self::joined(&mut state);
492                #[cfg(test)]
493                if let Some(probe) = &self.probe {
494                    probe.joined();
495                }
496            }
497        }
498        for slot in 0..state.tasks.len() {
499            let Some(task) = state.tasks[slot].take() else {
500                continue;
501            };
502            let bytes = task.bytes;
503            match task.running {
504                Running::Joined(result) => drop(result),
505                Running::Failed(error) => drop(error),
506                Running::TreeFailed(error) => drop(error),
507                Running::Panicked(payload) => drop(payload),
508                Running::Worker(_) | Running::Empty => {
509                    unreachable!("all workers were joined before disposal")
510                }
511            }
512            drop(task.path);
513            drop(task.id);
514            state.live_jobs = state
515                .live_jobs
516                .checked_sub(1)
517                .expect("discarded job retains its fixed slot charge");
518            self.account
519                .borrow_mut()
520                .with_memory(|memory| memory.release_bytes(bytes))
521                .expect("destroyed parser task must retain its original admitted layout");
522        }
523        let tasks = std::mem::take(&mut state.tasks);
524        self.account
525            .borrow_mut()
526            .with_memory(|memory| memory.release_vec(tasks))
527            .expect("destroyed parser slots must retain their original admitted layout");
528    }
529
530    fn start(
531        &self,
532        slot: usize,
533        mut task: Task<'scope>,
534        text: String,
535        max_tokens: usize,
536    ) -> Task<'scope> {
537        task.running = panic::catch_unwind(AssertUnwindSafe(|| {
538            self.start_worker(slot, &task.path, text, max_tokens)
539        }))
540        .unwrap_or_else(Running::Panicked);
541        task
542    }
543
544    fn prepare(
545        &self,
546        candidate: Candidate<'_>,
547    ) -> Result<Option<PreparedCandidate<'scope>>, StorageError> {
548        let mut admission = OwnedAdmission::new(PreparationAdmission {
549            account: self.account,
550            bytes: 0,
551        });
552        let path =
553            Memory::new(&mut admission).scope(|memory| Self::prepare_path(candidate, memory))?;
554        Ok(path.map(|path| PreparedCandidate { path, admission }))
555    }
556
557    fn prepare_path(
558        candidate: Candidate<'_>,
559        memory: &mut Memory<'_, OwnedAdmission<PreparationAdmission<'_>>>,
560    ) -> Result<Option<RelPath>, StorageError> {
561        match candidate {
562            Candidate::Existing(path) => {
563                memory.add_bytes(path.owned_layout()?)?;
564                Ok(Some(path.clone()))
565            }
566            Candidate::Joined {
567                base,
568                stem,
569                input,
570                suffix,
571            } => {
572                let intermediate = if let Some(stem) = stem {
573                    let Some(path) = base.join_admitted(stem, memory)? else {
574                        return Ok(None);
575                    };
576                    Some(path)
577                } else {
578                    None
579                };
580                let tail = if suffix.is_empty() {
581                    None
582                } else {
583                    Some(memory.format(&format_args!("{input}{suffix}"))?)
584                };
585                let path = intermediate
586                    .as_ref()
587                    .unwrap_or(base)
588                    .join_admitted(tail.as_deref().unwrap_or(input), memory)?;
589                if let Some(tail) = tail {
590                    memory.release_string(tail)?;
591                }
592                if let Some(intermediate) = intermediate {
593                    let bytes = intermediate.owned_layout()?;
594                    drop(intermediate);
595                    memory.release_bytes(bytes)?;
596                }
597                Ok(path)
598            }
599        }
600    }
601
602    fn start_worker(
603        &self,
604        slot: usize,
605        path: &RelPath,
606        text: String,
607        max_tokens: usize,
608    ) -> Running<'scope> {
609        let prepared = PreparedSource::new(path, &text, max_tokens);
610        match prepared {
611            Err(error) => Running::Failed(error),
612            Ok(prepared) => {
613                let scan = prepared.scan;
614                let control = &self.controls[slot];
615                control.set(Grant::Pending);
616                let input = WorkerInput {
617                    file: path.clone(),
618                    text,
619                    scan,
620                    control,
621                    configurations: self.configurations,
622                    #[cfg(test)]
623                    probe: self.probe.clone(),
624                };
625                match std::thread::Builder::new()
626                    .stack_size(PARSE_STACK_BYTES)
627                    .spawn_scoped(self.scope, move || input.run())
628                {
629                    Ok(worker) => {
630                        #[cfg(test)]
631                        if let Some(probe) = &self.probe {
632                            probe.started();
633                        }
634                        Running::Worker(worker)
635                    }
636                    Err(source) => {
637                        Running::Failed(LoadError::new(path, None, LoadErrorKind::Spawn(source)))
638                    }
639                }
640            }
641        }
642    }
643}
644
645impl Parser for Executor<'_, '_> {
646    fn has_capacity(&self) -> bool {
647        self.state
648            .borrow()
649            .tasks
650            .iter()
651            .skip(1)
652            .any(Option::is_none)
653    }
654
655    fn resize_frontier(&self, previous: usize, next: usize) -> Result<(), StorageError> {
656        self.account.borrow_mut().with_memory(|memory| {
657            if next >= previous {
658                memory.add_bytes(next - previous)
659            } else {
660                memory.release_bytes(previous - next)
661            }
662        })
663    }
664
665    fn speculate(
666        &self,
667        tree: &dyn Tree,
668        candidate: Candidate<'_>,
669        options: &LoadOptions,
670        seen: &dyn Fn(&FileId) -> bool,
671    ) -> bool {
672        let path = match candidate {
673            Candidate::Existing(path) | Candidate::Joined { base: path, .. } => path,
674        };
675        if matches!(
676            self.configurations,
677            Some((_, ExtractionConfigurations::Locked(_)))
678        ) && path.authority() != SourceAuthorityId::FIRST_PARTY
679        {
680            // Sealed backends charge the canonical budget during their reads.
681            return true;
682        }
683        let mut state = self.state.borrow_mut();
684        // Slot zero always belongs to canonical progress, including a newly
685        // discovered descendant that sorts before every parked sibling.
686        let Some(slot) = (1..state.tasks.len()).find(|slot| state.tasks[*slot].is_none()) else {
687            return false;
688        };
689        let Ok(Some(prepared)) = self.prepare(candidate) else {
690            return true;
691        };
692        let path = &prepared.path;
693        if state.tasks.iter().flatten().any(|task| task.path == *path) {
694            return true;
695        }
696        let opened = panic::catch_unwind(AssertUnwindSafe(|| {
697            tree.read_unseen(path, options.max_file_bytes, &|id| {
698                seen(id)
699                    || state
700                        .tasks
701                        .iter()
702                        .flatten()
703                        .any(|task| task.id.as_ref() == Some(id))
704            })
705        }));
706        let (id, text, deferred) = match opened {
707            Ok(Ok(Opened::Seen(_))) => {
708                return true;
709            }
710            Ok(Ok(Opened::Read { id, text })) => (Some(id), Some(text), None),
711            Ok(Err(error)) => (None, None, Some(Running::TreeFailed(error))),
712            Err(payload) => (None, None, Some(Running::Panicked(payload))),
713        };
714        let extra = text
715            .as_ref()
716            .map_or(0, String::capacity)
717            .checked_add(id.as_ref().map_or(0, FileId::heap_bytes));
718        if extra.is_none()
719            || self
720                .account
721                .borrow_mut()
722                .with_memory(|memory| {
723                    memory.add_bytes(extra.expect("a representable total has an extra layout"))
724                })
725                .is_err()
726        {
727            drop(text);
728            drop(id);
729            return true;
730        }
731        let bytes = extra.expect("the admitted layout is representable");
732        let PreparedCandidate { path, admission } = prepared;
733        let task = Task {
734            path,
735            id,
736            running: deferred.unwrap_or(Running::Empty),
737            bytes,
738            _path_admission: Some(admission),
739        };
740        let task = if let Some(text) = text {
741            self.start(slot, task, text, options.max_file_tokens)
742        } else {
743            task
744        };
745        Self::admitted(&mut state, &task);
746        state.tasks[slot] = Some(task);
747        true
748    }
749
750    fn parse(
751        &self,
752        path: &RelPath,
753        id: &FileId,
754        text: String,
755        options: &LoadOptions,
756        extraction: ExtractionGrant,
757    ) -> Result<Parsed, LoadError> {
758        let (slot, task, observed) = {
759            let mut state = self.state.borrow_mut();
760            if let Some(slot) = state.tasks.iter().position(|task| {
761                task.as_ref()
762                    .is_some_and(|task| task.id.as_ref() == Some(id))
763            }) {
764                let task = state.tasks[slot]
765                    .take()
766                    .expect("the selected task slot is occupied");
767                (slot, task, Some(text))
768            } else {
769                let task = self.start(
770                    0,
771                    Task {
772                        path: path.clone(),
773                        id: Some(id.clone()),
774                        running: Running::Empty,
775                        bytes: 0,
776                        _path_admission: None,
777                    },
778                    text,
779                    options.max_file_tokens,
780                );
781                Self::admitted(&mut state, &task);
782                (0, task, None)
783            }
784        };
785        self.controls[slot].set(Grant::Extract(HeadGrant {
786            path: path.clone(),
787            extraction,
788        }));
789        let result = match task.running {
790            Running::Failed(error) => Err(error),
791            Running::Worker(worker) => {
792                let result = worker.join();
793                Self::joined(&mut self.state.borrow_mut());
794                #[cfg(test)]
795                if let Some(probe) = &self.probe {
796                    probe.joined();
797                }
798                match result {
799                    Ok(result) => result,
800                    Err(payload) => panic::resume_unwind(payload),
801                }
802            }
803            Running::Panicked(payload) => panic::resume_unwind(payload),
804            Running::TreeFailed(_) | Running::Joined(_) | Running::Empty => {
805                unreachable!("only parser outcomes can be parsed")
806            }
807        };
808        // Destroy the speculative identity owners before refunding their charge.
809        // A worker panic retains the grant until Resources destruction instead.
810        drop(task.path);
811        drop(task.id);
812        let result = (|| {
813            let mut parsed = result
814                .map_err(|mut error| {
815                    error.file = path.clone();
816                    error
817                })?
818                .ok_or_else(|| {
819                    LoadError::new(
820                        path,
821                        None,
822                        LoadErrorKind::Internal {
823                            what: "the canonical parser task was cancelled".into(),
824                        },
825                    )
826                })?;
827            if let Some(observed) = observed {
828                if observed != parsed.text {
829                    return Err(LoadError::new(path, None, LoadErrorKind::Internal {
830                        what: "source changed between speculative parsing and canonical observation".into(),
831                    }));
832                }
833                // Keep the bytes from the canonical Tree observation in the index.
834                parsed.text = observed;
835            }
836            Ok(parsed)
837        })();
838        // The speculative text has now died or been replaced by canonical text;
839        // the returned value belongs to the canonical source accounting.
840        self.account
841            .borrow_mut()
842            .with_memory(|memory| memory.release_bytes(task.bytes))
843            .map_err(|cause| storage(path, cause))?;
844        let mut state = self.state.borrow_mut();
845        state.live_jobs = state
846            .live_jobs
847            .checked_sub(1)
848            .expect("consumed job retains its fixed slot charge");
849        result
850    }
851}
852
853impl Drop for Executor<'_, '_> {
854    fn drop(&mut self) {
855        self.cleanup();
856    }
857}