#[non_exhaustive]pub struct Budget {
pub max_depth: u32,
pub max_expansions: usize,
pub max_tokens: usize,
}Expand description
The limits an Expander enforces on the work it does.
| Field | Limits | Default | Exceeding it reports |
|---|---|---|---|
max_depth | How deeply invocations may nest. | 128 | ExpandError::RecursionLimit |
max_expansions | Successful expansions since creation or the last reset_usage. | 1 048 576 (2^20) | ExpandError::Budget(Limit::Expansions) |
max_tokens | Tokens written since creation or the last reset_usage. | 4 194 304 (2^22) | ExpandError::Budget(Limit::Tokens) |
Every expander has a budget; Expander::new uses
Budget::DEFAULT. The expansion and token counts are cumulative: they
accumulate in the expander’s Usage until
Expander::reset_usage zeroes them. A
batch compiler uses one expander per compilation and never resets, so the
budget bounds the compilation’s total macro output; a long-lived host (a
language server, a REPL, a watch-mode compiler) resets once per unit of
work — per document parse, per REPL entry, per compilation — so the budget
bounds each unit instead of the host’s lifetime.
The defaults are well above what typical programs expand to, and stop a
runaway macro quickly: the doubling macro in examples/budget stops in
about 0.2 s (release build) with a whole-process peak of about 400 MB.
Memory grows in proportion to max_tokens, so lower it where that is too
much; a unit of work that legitimately needs more can raise the budget with
Expander::set_budget.
Tokens are counted as they are written: one per token, two per group (its
delimiters), and every token of a substituted capture. An expansion that
would push the total past max_tokens stops as soon as it does, so even a
single enormous expansion allocates no more than the budget allows.
A failed expansion is not charged: like every other error it leaves the expander exactly as it was.
The struct is #[non_exhaustive] so that further limits can be added in a
minor release. Start from Budget::DEFAULT (or Budget::default) and
adjust it with the with_* methods, or assign the public fields.
§Examples
use macro_lang::{Budget, Expander};
let budget = Budget::DEFAULT.with_max_depth(32).with_max_tokens(1 << 16);
let expander: Expander<char> = Expander::with_budget(budget);
assert_eq!(expander.budget().max_depth, 32);
assert_eq!(expander.budget().max_tokens, 65_536);
assert_eq!(expander.budget().max_expansions, Budget::DEFAULT.max_expansions);
assert_eq!(expander.limit(), 32);Fields (Non-exhaustive)§
This struct is marked as non-exhaustive
Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.max_depth: u32The deepest an invocation may be nested: an invocation in source runs at
depth 1, one produced by that expansion at depth 2, and so on. Exceeding
it reports ExpandError::RecursionLimit.
0 rejects every expansion. This is the recursion limit that
Expander::with_limit sets.
max_expansions: usizeThe number of successful expansions the expander may perform before
its Usage is reset. 0 rejects
every expansion.
max_tokens: usizeThe number of tokens the expander may write before its Usage is
reset, counting group delimiters and
substituted captures.
Implementations§
Source§impl Budget
impl Budget
Sourcepub const DEFAULT: Self
pub const DEFAULT: Self
The budget Expander::new uses: depth 128 (the
same default as rustc’s recursion_limit), 2^20 expansions, and
2^22 tokens.
§Examples
use macro_lang::Budget;
assert_eq!(Budget::DEFAULT.max_depth, 128);
assert_eq!(Budget::DEFAULT.max_expansions, 1 << 20);
assert_eq!(Budget::DEFAULT.max_tokens, 1 << 22);
assert_eq!(Budget::default(), Budget::DEFAULT);Sourcepub const fn with_max_depth(self, max_depth: u32) -> Self
pub const fn with_max_depth(self, max_depth: u32) -> Self
Sourcepub const fn with_max_expansions(self, max_expansions: usize) -> Self
pub const fn with_max_expansions(self, max_expansions: usize) -> Self
Returns this budget with max_expansions
replaced.
§Examples
use macro_lang::Budget;
assert_eq!(Budget::DEFAULT.with_max_expansions(10).max_expansions, 10);Sourcepub const fn with_max_tokens(self, max_tokens: usize) -> Self
pub const fn with_max_tokens(self, max_tokens: usize) -> Self
Returns this budget with max_tokens replaced.
§Examples
use macro_lang::Budget;
assert_eq!(Budget::DEFAULT.with_max_tokens(1000).max_tokens, 1000);