Module stack_guard 

Configurable native-stack growth guard for deeply-recursive digestion.

Some inputs recurse through the engine far deeper than a normal document: gullet macro expansion (a number-argument macro whose argument is read by expanding the next number-argument macro — xint’s \XINT_… chains nest tens of thousands deep), the document tree walk, and the math-tree walk. Left unguarded these overflow the (large but finite) conversion-thread stack and abort the process (SIGABRT) — whereas Perl degrades gracefully via its $MAXSTACK guard. Each such site therefore grows the native stack on demand with [stacker::maybe_grow].

This module is the single home for the two parameters those calls share, so they are tuned in one place and are configurable at runtime rather than hardcoded:

• red zone — grow once fewer than this many bytes of stack remain.
• segment — the size of each freshly-allocated stack chunk.

Resolution precedence (highest first): an explicit set_red_zone_bytes / set_segment_bytes (e.g. from a future --stack-… CLI flag) → the env var (ENV_RED_ZONE / ENV_SEGMENT, a plain byte count) → the compiled default. Call maybe_grow at every deeply-recursive site instead of stacker::maybe_grow directly.

Constants

DEFAULT_RED_ZONE_BYTES

Default red zone: grow when within this many bytes of the stack end. 256 KiB leaves ample margin above any single recursion frame.

DEFAULT_SEGMENT_BYTES

Default growth segment: bytes of fresh stack allocated per growth step. 8 MiB amortizes the allocation across many recursion levels.

ENV_RED_ZONE

Env override for the red zone — a plain byte count (e.g. 262144).

ENV_SEGMENT

Env override for the growth segment — a plain byte count (e.g. 8388608).

Functions

maybe_grow

Grow the native call stack on demand, then run f. The single wrapper every deeply-recursive site should call so the guard parameters live in one place. Transparent: it only provides more stack when near the limit; it never changes results.

red_zone_bytes

Bytes of remaining stack below which maybe_grow allocates a new segment.

segment_bytes

Size, in bytes, of each freshly-allocated stack segment.

set_red_zone_bytes

Override the red zone (e.g. from a CLI flag). Set before any conversion; takes precedence over the env var and the default.

set_segment_bytes

Override the growth segment (e.g. from a CLI flag). Set before any conversion; takes precedence over the env var and the default.