Skip to main content

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}