FixedStack: Safe and Unsafe Stack Implementations in Rust

This project demonstrates two implementations of a stack in Rust: a safe implementation using Vec and an unsafe implementation using raw pointers for manual memory management. The project includes:

Benchmarks: Comparing performance between safe and unsafe implementations using criterion.
Fuzzing: Testing the robustness of the stack implementations using cargo-fuzz.

Features

Safe Implementation:
- Uses Vec for memory safety.
- Minimal risk of undefined behavior.
Unsafe Implementation:
- Manages memory manually using raw pointers.
- Optimized for performance-critical use cases.
- Tests allocation, deallocation, and pointer arithmetic.

Requirements

cargo for building and managing dependencies

For benchmarks and fuzzing:

Install criterion for benchmarks.
Install cargo-fuzz for fuzz testing (requires nightly toolchain).

Getting Started

Clone the Repository

git clone https://github.com/sunsided/fixedstack-rs.git
cd fixedstack-rs

Build the Project

just build
 # or
cargo build

Run Tests

just test
 # or
cargo test

Benchmarks

Benchmarks are implemented using the Criterion crate. To run benchmarks:

just bench
 # or
cargo bench

This compares the performance of push and pop operations for both safe and unsafe stack implementations.

Fuzzing

Fuzz tests are implemented using cargo-fuzz. Fuzzing helps uncover edge cases and undefined behavior, especially in the unsafe implementation.

Install `cargo-fuzz`

cargo install cargo-fuzz

Run the Fuzzer

just fuzz
 # or
cargo fuzz run fuzz_stack

Debug Failing Inputs

When the fuzzer finds a failing input, the test case is saved in fuzz/artifacts/fuzz_stack/. To reproduce the failure:

cargo fuzz run fuzz_stack fuzz/artifacts/fuzz_stack/<failing-input>

You can also minimize failing inputs for easier debugging:

cargo fuzz tmin fuzz_stack fuzz/artifacts/fuzz_stack/<failing-input>

Project Structure

.
├── src
│   ├── lib.rs                # Main library code for stack implementations
│   ├── stack_safe.rs         # Safe stack implementation
│   └── stack_unsafe.rs       # Unsafe stack implementation
│
├── benches
│   └── benchmarks.rs         # Criterion benchmarks
│
└── fuzz
    ├── fuzz_targets          # Directory for fuzzing targets
    └── fuzz_stack.rs         # Fuzz target for stack testing

Example Usage

Safe FixedStack

use stack_experiments::stack_unsafe::FixedStack;

fn main() {
    let mut stack = FixedStack::new(3);
    stack.push(1);
    stack.push(2);
    println!("{:?}", stack.pop()); // Output: Some(2)
    println!("{:?}", stack.pop()); // Output: Some(1)
}

Unsafe FixedStack

use stack_experiments::stack_unsafe::FixedStack;

fn main() {
    let mut stack = FixedStack::new(3);
    stack.push(1);
    stack.push(2);
    println!("{:?}", stack.pop()); // Output: Some(2)
    println!("{:?}", stack.pop()); // Output: Some(1)
}

Contributions

Contributions are welcome! Feel free to fork the repository, create a feature branch, and submit a pull request.

License

This project is licensed under the EUPL-1.2 License. See LICENSE for details.

sunsided/fixedstack-rs