raf_source/options.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//! Caller-set limits for loading a workspace.
5
6use crate::budget::Budget;
7
8/// The default cap on one file: 8 MiB.
9pub const DEFAULT_MAX_FILE_BYTES: u64 = 8 * 1024 * 1024;
10
11/// Limits a caller sets for one load.
12///
13/// The token budget, the byte budgets and the work budgets of the load and
14/// of each query after it default to the limits of [`Budget::FileTokens`],
15/// [`Budget::TotalBytes`], [`Budget::ItemBytes`], [`Budget::FactBytes`],
16/// [`Budget::GlobBytes`] and [`Budget::Work`]. A load that passes one is
17/// refused with
18/// [`LoadErrorKind::Budget`](crate::LoadErrorKind::Budget), naming the budget,
19/// the limit that applied and the file.
20///
21/// The options are `Clone` and not `Copy`, so adding an option that is not
22/// `Copy`, such as a per-file hook, is not a breaking change.
23#[derive(Debug, Clone, PartialEq, Eq)]
24#[non_exhaustive]
25pub struct LoadOptions {
26 /// The most bytes one file may hold. A larger file is refused with
27 /// [`TreeError::TooLarge`](crate::TreeError::TooLarge). Defaults to
28 /// [`DEFAULT_MAX_FILE_BYTES`].
29 pub max_file_bytes: u64,
30 /// The most tokens one file may hold, counted by the pre-scan before the
31 /// file is parsed. This bounds token structure, not the complete native
32 /// parser heap or work. [`PARSE_BYTES_PER_TOKEN`](crate::PARSE_BYTES_PER_TOKEN)
33 /// records one empirical statement-shape measurement; source-byte payloads
34 /// and transient native storage require separate accounting.
35 pub max_file_tokens: usize,
36 /// The most bytes one load may read, source files and manifests together.
37 /// Defaults to the limit of [`Budget::TotalBytes`].
38 pub max_total_bytes: usize,
39 /// The cumulative bytes of index records, entries built for each module
40 /// path, native load traversal spills and immutable derived glob facts,
41 /// including their shared allocation header. Defaults to the limit of
42 /// [`Budget::ItemBytes`].
43 pub max_item_bytes: usize,
44 /// The most bytes the facts of the files of one load may hold. Defaults to
45 /// the limit of [`Budget::FactBytes`].
46 pub max_fact_bytes: usize,
47 /// The most bytes import settling may hold at once: glob scope tables,
48 /// retained reads, queues, subscriptions, graph scratch and impl self-type
49 /// and trait-path traversal scratch, plus derived glob-fact construction.
50 /// Also bounds
51 /// transient selected-route determinacy proofs of each query after the
52 /// load, counted from zero and released before it returns. Defaults to
53 /// the limit of [`Budget::GlobBytes`].
54 pub max_glob_bytes: usize,
55 /// The most import-settling and impl self-type and trait-path traversal
56 /// steps one load may make, including retained path segments and bytes, counted as they
57 /// are made and never given back (see [`Budget::Work`]). Defaults to the
58 /// limit of [`Budget::Work`].
59 pub max_work: usize,
60 /// The most lookup and selected-route proof steps one query after the
61 /// load may make: a call of
62 /// [`Workspace::resolve`](crate::Workspace::resolve), its variants or
63 /// [`Workspace::exported_items_with`](crate::Workspace::exported_items_with),
64 /// each counted from zero. A query that passes it fails with
65 /// [`ResolveError::Budget`](crate::ResolveError::Budget) or
66 /// [`ExportError::Budget`](crate::ExportError::Budget), naming
67 /// [`Budget::Work`] and this limit. Defaults to the limit of
68 /// [`Budget::Work`].
69 pub max_query_work: usize,
70}
71
72impl Default for LoadOptions {
73 fn default() -> Self {
74 Self {
75 max_file_bytes: DEFAULT_MAX_FILE_BYTES,
76 max_file_tokens: Budget::FileTokens.limit(),
77 max_total_bytes: Budget::TotalBytes.limit(),
78 max_item_bytes: Budget::ItemBytes.limit(),
79 max_fact_bytes: Budget::FactBytes.limit(),
80 max_glob_bytes: Budget::GlobBytes.limit(),
81 max_work: Budget::Work.limit(),
82 max_query_work: Budget::Work.limit(),
83 }
84 }
85}