https://github.com/cong-or/snarf
Cache-line false sharing linter for Rust structs
https://github.com/cong-or/snarf
cache-line ci concurrency false-sharing linter mesi no-std performance rust static-analysis
Last synced: 6 days ago
JSON representation
Cache-line false sharing linter for Rust structs
- Host: GitHub
- URL: https://github.com/cong-or/snarf
- Owner: cong-or
- License: mit
- Created: 2026-05-04T16:19:50.000Z (2 months ago)
- Default Branch: main
- Last Pushed: 2026-05-25T14:48:44.000Z (about 2 months ago)
- Last Synced: 2026-05-25T16:33:58.438Z (about 2 months ago)
- Topics: cache-line, ci, concurrency, false-sharing, linter, mesi, no-std, performance, rust, static-analysis
- Language: Rust
- Homepage:
- Size: 627 KB
- Stars: 3
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- Awesome-Rust-Checker - snarf - line false sharing linter for Rust structs — detects potential cache-line false sharing by finding cases where atomic or contended fields share a cache line | Source Code | Cache-line false sharing (performance) | Layout analysis | 2026-05-25 | (Linters)
README
# snarf
Cache-line false sharing linter for Rust structs.
---
Finds Rust structs where atomic or contended fields share a cache line with other fields. This is potential false sharing, not proven — snarf detects the layout but not runtime behavior, so you decide which fields are actually contended.
[The Slowdown That Doesn't Show Up in Profiles](https://cong-or.xyz/false-sharing-cache-lines.html) — why this matters.
---
### Install and run
```
cargo install cargo-snarf
cargo snarf
```
No output means no issues found. If snarf finds contended fields sharing a cache line, it prints a layout diagram and exits non-zero. In a workspace it discovers all crates automatically.
snarf requires nightly Rust to get exact type sizes via `cargo +nightly build -Zprint-type-sizes`. Install it:
```
rustup toolchain install nightly
```
### CI
```yaml
- name: Cache-line sanity check
run: |
rustup toolchain install nightly --profile minimal
cargo install cargo-snarf && cargo snarf
```
For PR annotations without blocking:
```yaml
- name: Cache-line annotations
run: |
rustup toolchain install nightly --profile minimal
cargo install cargo-snarf && cargo snarf --format github --warn-only
```
This repo runs snarf on itself — see [ci.yml](.github/workflows/ci.yml).
### Options
| Flag | What it does |
|------|-------------|
| `--strict` | Warn on all multi-field cache lines, not just contended ones |
| `--format json` | Machine-readable output |
| `--format github` | GitHub Actions annotations on the PR diff |
| `--warn-only` | Report issues but exit 0 |
| `--threshold N` | Minimum fields per line to warn (default: 2) |
| `--line-size N` | Cache line size in bytes (default: 64, use 128 for Apple M-series) |
| `--no-send-sync-check` | Warn even on `!Send`/`!Sync` structs (see below) |
| `--color never` | No ANSI escape codes |
By default snarf only warns when an `Atomic*`/`Cell`/`RefCell`/`UnsafeCell` field shares a cache line with other fields. Detection is recursive, so `Option` and `Arc>` are both caught. `--strict` warns on all multi-field lines regardless.
Structs containing `!Send` or `!Sync` types (`Rc`, `Cell`, `RefCell`, raw pointers, lock guards) are automatically suppressed since they can't be shared across threads, making false sharing impossible. Suppressed structs print a note to stderr. Use `--no-send-sync-check` to disable this and warn on all structs.
---
### How it works
Parses structs with `syn`, then gets exact type sizes and field offsets from `cargo +nightly build -Zprint-type-sizes`. This resolves all types (custom structs, enums, non-repr(C) layouts, niche-optimized `Option`s) with no guessing.
- All types resolved, including custom and cross-crate types
- Non-repr(C) structs get exact field offsets from the compiler
- Niche optimization (`Option<&T>`, `Option`) handled correctly
### Validation
The `validation/` directory has a controlled experiment that correlates snarf's static warnings with real hardware cache-line contention measured by `perf c2c`. Two `#[repr(C)]` structs (one with co-located atomics, one with cache-line padding) are hammered from threads pinned to separate P-cores. The script runs snarf and `perf c2c`, then compares HITM event counts to snarf's warnings.
```
cd validation && ./run.sh # requires sudo for perf c2c
```
### Limitations
- `repr(packed)` not yet supported
- Type name collisions: if two modules define a type with the same name (e.g. `a::Config` and `b::Config`), only the first is used (a warning is printed)
### Name
[snarf](http://www.catb.org/jargon/html/S/snarf.html) — hacker slang: to grab data greedily.
### License
MIT