memtools

memtools explores page-level memory tracking using two mechanisms:

• Linux userfaultfd for demand paging and write-protect tracking
• mprotect + SIGSEGV for signal-based dirty-page tracking

The repository contains both a Rust crate and small C++ reference programs that exercise the same ideas.

Repository layout

• rust/ — primary Rust crate, tests, benchmarks, and demo binaries
• cpp/ — small C++ programs for userfaultfd and SIGSEGV
• docs/ — design notes and implementation tradeoffs

Current status

This is still an experimental systems project. The code is useful, but the repository is organized as a research-oriented prototype rather than a polished library release.

Platform support

• userfaultfd support is Linux-only
• SIGSEGV tracking is the portability path for non-Linux Unix systems
• The current codebase assumes Unix APIs and is not Windows-oriented

Rust quickstart

From rust/:

cargo build
cargo test

Run the demo binary:

cargo run

Run the stress binary:

cargo run --bin stress

Run benchmarks:

cargo bench --bench simple
cargo bench --bench criterion

C++ quickstart

From cpp/:

make run

Build only:

make test-userfaultfd
make test-sigsegv

Core Rust API

The Rust crate allows creating memory areas with page-access tracking using either userfaultfd or SIGSEGV.

Tracked memory can optionally be backed by a storage file descriptor. When present, pages are initialized from that descriptor and modified pages can later be committed back to storage.

If no storage file descriptor is provided, the memory is zero-initialized.

See:

• rust/src/main.rs for the current demo program
• rust/tests/sigsegv.rs for the signal-based test flow
• docs/design.md for deeper implementation notes

Notes

• userfaultfd avoids the VMA-splitting overhead that comes with repeated mprotect changes.
• The signal-based path is easier to prototype but harder to compose safely in larger applications because signal handlers are process-global.