Skip to main content

Budget

Struct Budget 

Source
#[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.

FieldLimitsDefaultExceeding it reports
max_depthHow deeply invocations may nest.128ExpandError::RecursionLimit
max_expansionsSuccessful expansions since creation or the last reset_usage.1 048 576 (2^20)ExpandError::Budget(Limit::Expansions)
max_tokensTokens 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
Non-exhaustive structs could have additional fields added in future. Therefore, non-exhaustive structs cannot be constructed in external crates using the traditional Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.
§max_depth: u32

The 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: usize

The number of successful expansions the expander may perform before its Usage is reset. 0 rejects every expansion.

§max_tokens: usize

The number of tokens the expander may write before its Usage is reset, counting group delimiters and substituted captures.

Implementations§

Source§

impl Budget

Source

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);
Source

pub const fn with_max_depth(self, max_depth: u32) -> Self

Returns this budget with max_depth replaced.

§Examples
use macro_lang::Budget;

assert_eq!(Budget::DEFAULT.with_max_depth(8).max_depth, 8);
Source

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);
Source

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);

Trait Implementations§

Source§

impl Clone for Budget

Source§

fn clone(&self) -> Self

Returns a duplicate of the value. Read more
1.0.0 (const: unstable) · Source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more
Source§

impl Copy for Budget

Source§

impl Debug for Budget

Source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more
Source§

impl Default for Budget

Source§

fn default() -> Self

Returns Budget::DEFAULT.

Source§

impl Eq for Budget

Source§

impl Hash for Budget

Source§

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher. Read more
1.3.0 · Source§

fn hash_slice<H>(data: &[Self], state: &mut H)
where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher. Read more
Source§

impl PartialEq for Budget

Source§

fn eq(&self, other: &Self) -> bool

Equality operator ==. Read more
1.0.0 (const: unstable) · Source§

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=. Read more
Source§

impl StructuralPartialEq for Budget

Auto Trait Implementations§

§

impl Forget for Budget

§

impl Freeze for Budget

§

impl Move for Budget

§

impl RefUnwindSafe for Budget

§

impl Send for Budget

§

impl Sync for Budget

§

impl Unpin for Budget

§

impl UnsafeUnpin for Budget

§

impl UnwindSafe for Budget

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.