StackSafe

StackSafe prevents stack overflows in deeply recursive algorithms by providing intelligent stack management. No more crashes from recursive functions or data structures that exceed the default stack size - StackSafe automatically allocates additional stack space when needed, eliminating the need for manual stack size tuning or complex refactoring to iterative approaches.

Quick Start

Add StackSafe to your Cargo.toml:

[dependencies]
stacksafe = "1"

Transform recursive functions with the #[stacksafe] attribute to prevent stack overflow:

use stacksafe::stacksafe;#[stacksafe]fnfibonacci(n:u64) -> u64{match n {0 | 1 => n,
_ => fibonacci(n - 1) + fibonacci(n - 2),}}// No stack overflow, even for deep recursionprintln!("Fibonacci of 30: {}", fibonacci(30));

Recursive Data Structures

Use StackSafe<T> to wrap recursive data structures and prevent stack overflow during traversal:

use stacksafe::{stacksafe,StackSafe};#[derive(Debug,Clone)]enumBinaryTree{Leaf(i32),Node{value:i32,left:Box<StackSafe<BinaryTree>>,right:Box<StackSafe<BinaryTree>>,},}#[stacksafe]fntree_sum(tree:&BinaryTree) -> i32{match tree {BinaryTree::Leaf(value) => *value,BinaryTree::Node{ value, left, right } => {
value + tree_sum(left) + tree_sum(right)}}}

How It Works

• #[stacksafe] attribute monitors remaining stack space at function entry points. When available space falls below a threshold (default: 128 KiB), it automatically allocates a new stack segment (default: 2 MiB) and continues execution.
• StackSafe<T> is a wrapper type that transparently implement common traits like Clone, Debug, and PartialEq with #[stacksafe] support, allowing you to use it in recursive data structures without losing functionality.
• In debug builds, accessing StackSafe<T> performs additional checks to ensure the current function is properly annotated with #[stacksafe], helping catch potential issues during development.

Read this blog post for an in-depth explanation of StackSafe's design and implementation.

Configuration

Customize stack management behavior:

use stacksafe::{set_minimum_stack_size, set_stack_allocation_size};// Trigger allocation when < 64 KiB remaining (default: 128 KiB).set_minimum_stack_size(64*1024);// Allocate 4 MiB stacks for deep recursion (default: 2 MiB).set_stack_allocation_size(4*1024*1024);

Feature Flags

StackSafe supports several optional features:

• serde: Provides stack-safe serialization and deserialization for StackSafe<T>.

Platform Support

StackSafe works on all major platforms supported by the stacker crate, including:

• Linux (x86_64, ARM64, others)
• macOS (Intel, Apple Silicon)
• Windows (MSVC, GNU)
• FreeBSD, NetBSD, OpenBSD
• And more...

License

This project is licensed under the Apache-2.0 license.

Acknowledgments

Inspired by the the excellent recursive by Orson Peters.