README-rust.md

Major Page Fault Generator - Rust Version

This is a Rust rewrite of the original C program that demonstrates major page faults by memory-mapping files and reading through them to generate I/O load.

What it does

• Memory-maps a file using mmap (via the memmap2 crate)
• Uses posix_fadvise to tell the kernel not to cache the file (POSIX_FADV_DONTNEED)
• Reads through the entire file byte by byte to trigger major page faults
• Runs this in a loop to generate sustained I/O load
• Uses sar -B to monitor page fault statistics

Key differences from the C version

• Uses Rust's memory safety features while maintaining equivalent functionality
• Uses the memmap2 crate for safe memory mapping
• Uses libc crate for direct system calls like posix_fadvise
• Proper error handling with Rust's Result type
• Uses wrapping_add to handle integer overflow safely

Building and Running

Local build:

cargo build --release
./target/release/majorfault <filename>

Docker build:

cd docker
make -f Makefile.rust build
docker run --rm mjpf-rust

Files

• src/main.rs - Main Rust implementation
• Cargo.toml - Rust project configuration with dependencies
• docker/Dockerfile.rust - Multi-stage Docker build for Rust version
• docker/Makefile.rust - Build automation for Docker
• docker/load.sh - Shell script to run the program in a loop (unchanged)
• docker/bootsrap.sh - Bootstrap script to start load generation and monitoring (unchanged)

Dependencies

• memmap2 - Safe memory mapping
• libc - Direct access to system calls

Behavior

The program behaves identically to the original C version:

• Takes a filename as command line argument
• Memory maps the file
• Advises the kernel not to cache it
• Reads through every byte to trigger page faults
• Returns the sum of all bytes as exit code (modulo 256)

This generates major page faults that are visible across containers but the I/O is not multiplied, and can be capped by limiting IOPS.