If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/Amanieu/parking_lot shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit 3mo ago
• 30+ active contributors
• Apache-2.0 licensed
• CI configured
• Tests present
• ⚠ Concentrated ownership — top contributor handles 51% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live Amanieu/parking_lot repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/Amanieu/parking_lot.

What it runs against: a local clone of Amanieu/parking_lot — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in Amanieu/parking_lot | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 106 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of Amanieu/parking_lot. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/Amanieu/parking_lot.git
#   cd parking_lot
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of Amanieu/parking_lot and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "Amanieu/parking_lot(\\.git)?\\b" \\
  && ok "origin remote is Amanieu/parking_lot" \\
  || miss "origin remote is not Amanieu/parking_lot (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "src/lib.rs" \\
  && ok "src/lib.rs" \\
  || miss "missing critical file: src/lib.rs"
test -f "core/src/parking_lot.rs" \\
  && ok "core/src/parking_lot.rs" \\
  || miss "missing critical file: core/src/parking_lot.rs"
test -f "src/raw_mutex.rs" \\
  && ok "src/raw_mutex.rs" \\
  || miss "missing critical file: src/raw_mutex.rs"
test -f "core/src/thread_parker/mod.rs" \\
  && ok "core/src/thread_parker/mod.rs" \\
  || miss "missing critical file: core/src/thread_parker/mod.rs"
test -f "lock_api/src/lib.rs" \\
  && ok "lock_api/src/lib.rs" \\
  || miss "missing critical file: lock_api/src/lib.rs"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 106 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~76d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/Amanieu/parking_lot"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

parking_lot is a drop-in replacement for Rust's standard library synchronization primitives (Mutex, RwLock, Condvar, Once) that are 1.5–5× faster and use significantly less memory (Mutex only needs 1 byte). It provides optimized lock implementations with adaptive spinning, task-fair scheduling, and platform-specific optimizations (Windows keyed events, Linux futex, SGX/WASM support), plus a low-level parking_lot_core API for building custom primitives. Monorepo with three independent crates: parking_lot (top-level, v0.12.5) contains Mutex/RwLock/Condvar/Once logic (src/), core/parking_lot_core (v0.9.12) provides platform-specific thread parking (core/src/thread_parker/ has OS-specific implementations: linux.rs, windows/, unix.rs, wasm.rs, sgx.rs), and lock_api (v0.4.14) defines the generic lock traits. Benchmarks live in benchmark/ with platform-specific binaries.

Systems programmers, game developers, database engineers, and library authors in the Rust ecosystem who need high-performance synchronization with minimal memory overhead and guaranteed no spurious wakeups. Also used by anyone building concurrent data structures or requiring fine-grained locking strategies.

Highly mature and production-ready. The repo shows consistent maintenance (v0.12.5 released, Cargo.toml declares MSRV 1.84), comprehensive CI via GitHub Actions (rust.yml, release-plz.yml), and multi-year stability. It's widely adopted in the Rust ecosystem and considered the standard replacement for std sync primitives in performance-critical code.

Very low risk. Single-author (Amanieu d'Antras) with stable, minimal surface area and few external dependencies (only lock_api, parking_lot_core—both internal). No breaking changes visible in CHANGELOG pattern, and the dual MIT/Apache-2.0 licensing is industry standard. Main risk is single-maintainer dependency, but the crate's maturity and widespread use mitigate this.

Release management via release-plz (release-plz.yml, release-plz.toml). The project appears in stable maintenance mode with regular CI validation. No in-repo issue tracker visible in file list, but the CHANGELOG.md and version bumping suggest active, methodical releases.

git clone https://github.com/Amanieu/parking_lot.git
cd parking_lot
cargo build
cargo test
cargo doc --open

Daily commands:

# Run all tests
cargo test --all

# Run benchmarks
cd benchmark && cargo run --release --bin mutex
cargo run --release --bin rwlock

# With features
cargo test --all --features deadlock_detection,hardware-lock-elision

# Check with Miri (undefined behavior detection)
sh ci/miri.sh

• src/lib.rs — Main entry point exporting all public synchronization primitives (Mutex, RwLock, Condvar, Once, ReentrantMutex); every contributor must understand the public API surface
• core/src/parking_lot.rs — Core parking lot algorithm implementation handling thread parking/unparking; foundational to all contention management in the library
• src/raw_mutex.rs — Mutex implementation using parking_lot_core; demonstrates the pattern for building efficient synchronization primitives
• core/src/thread_parker/mod.rs — Platform abstraction layer for thread parking across OS-specific implementations (Linux, Windows, Unix, WASM); critical for portability
• lock_api/src/lib.rs — Type-safe lock API trait definitions; enables generic synchronization primitive implementations across the ecosystem
• src/raw_rwlock.rs — RwLock raw implementation demonstrating reader-writer lock mechanics and fairness trade-offs
• core/src/word_lock.rs — Low-level word-based locking primitive used internally; essential to understanding parking_lot's compact design

Add a new synchronization primitive using lock_api traits

1. Define a raw lock struct implementing RawMutex or RawRwLock trait from lock_api/src/lib.rs (lock_api/src/lib.rs)
2. Implement park/unpark calls using parking_lot_core (see src/raw_mutex.rs pattern) (src/raw_mutex.rs)
3. Create a public wrapper type in src/mylock.rs delegating to your raw implementation (src/lib.rs)
4. Export the new type from src/lib.rs and add unit tests (src/lib.rs)

Support a new operating system for thread parking

1. Create a new OS-specific file in core/src/thread_parker/ (e.g., thread_parker/myos.rs) (core/src/thread_parker/mod.rs)
2. Implement ThreadParker trait with park() and unpark() using OS primitives (core/src/thread_parker/mod.rs)
3. Update build.rs to detect your OS and select the correct implementation (core/build.rs)
4. Add conditional cfg flags in thread_parker/mod.rs to route to your implementation (core/src/thread_parker/mod.rs)

Add a new optional feature to the library

1. Add feature definition to [features] in Cargo.toml (Cargo.toml)
2. Create feature-gated code (e.g., #[cfg(feature = "myfeature")]) in src/myfeature.rs (src/lib.rs)
3. Conditionally export from src/lib.rs with #[cfg(feature = "myfeature")] (src/lib.rs)
4. Add integration tests in tests/ verifying feature behavior (tests/issue_203.rs)

Optimize contention behavior for a specific lock type

1. Review the raw implementation (e.g., src/raw_mutex.rs) and parking_lot algorithm in core/src/parking_lot.rs (src/raw_mutex.rs)
2. Adjust spinwait strategy in core/src/spinwait.rs or backoff constants in raw implementations (core/src/spinwait.rs)
3. Run benchmarks in benchmark/src/bin/mutex.rs to measure impact (benchmark/src/bin/mutex.rs)
4. Update CHANGELOG.md with performance notes and commit changes (CHANGELOG.md)

• Atomic operations (std::sync::atomic) — Lock-free fast path for uncontended access; enables sub-microsecond acquire times without syscalls
• OS-specific thread parking (futex, keyed events, condition variables) — Efficient sleep-and-wakeup mechanism reducing CPU spin time; platform abstraction layer accommodates Linux, Windows, POSIX systems
• Word-based locking (single atomic word state) — Minimizes memory overhead compared to std library; lock state + writer bit + parker bits fit in one word for smaller, cache-friendly structures
• Hash table for parking lot (core/parking_lot.rs) — Scales efficiently with many locks; avoids per-lock condition variable overhead by multiplexing multiple locks through one global parking lot

• Spin-wait before parking (core/spinwait.rs)

  • Why: Avoids syscall overhead for briefly-contended locks where spin-waiting is faster than park/unpark round trip
  • Consequence: Slightly higher CPU usage during contention, but faster median latency and reduced context switches

• Fair vs. unfair mutex variants (src/mutex.rs vs. src/fair_mutex.rs)

  • Why: Unfair mutex is faster (LIFO behavior); fair mutex prevents writer starvation in high-contention reader-writer scenarios
  • Consequence: Users must choose variant; unfair mutex may cause unbounded latency for some threads under sustained contention

• Global parking lot hash table instead of per-lock condition variables

  • Why: Memory-efficient and scales to many locks without allocating per-lock resources
  • Consequence: undefined

1. Platform-specific behavior: Miri cannot simulate thread parking fully (ci/miri.sh shows this is known), so some thread-safety bugs only surface on real OS (run full test suite on Linux/Windows/macOS). 2. Feature fragmentation: hardware-lock-elision is x86-only; deadlock_detection has runtime overhead. 3. MSRV is 1.84 (Cargo.toml)—don't use newer syntax. 4. OS parker selection is compile-time; you cannot swap at runtime (see thread_parker/mod.rs conditional compilation). 5. Condvar requeue optimization requires associated Mutex—using Condvar::notify_all with multiple Mutex instances will not requeue properly across them.

• Futex (Fast Userspace Mutex) — Linux implementation (core/src/thread_parker/linux.rs) relies on futex syscall for efficient kernel-assisted lock parking; understanding futex semantics is essential to debug contended lock behavior
• Adaptive Spinning — parking_lot spins a few iterations before parking the thread (core/src/spinwait.rs); this micro-contention optimization is why it beats std::sync on short critical sections
• Hardware Lock Elision (HLE) — Optional feature (hardware-lock-elision) leverages Intel TSX to speculatively execute critical sections without taking locks on supporting CPUs, enabling near-free parallelism for readers in RwLock
• Task-Fair Scheduling — parking_lot RwLock uses fair queuing to prevent reader/writer starvation, unlike std::sync::RwLock; this is why it scales predictably with mixed workloads
• Condvar Requeue Optimization — notify_all wakes only 1 waiter and requeues the rest on the associated Mutex (src/condvar.rs), avoiding thundering herd where all threads race for the lock—unique to parking_lot
• Bit-Packed Lock State (Word Lock) — core/src/word_lock.rs encodes lock status, thread ID, and flags in a single machine word; enables Mutex to use only 1 byte on most platforms vs large OS handles in std
• Platform Abstraction via Conditional Compilation — core/src/thread_parker/mod.rs uses #[cfg] to select OS-specific parking at compile time (linux.rs, windows/, unix.rs, wasm.rs); critical for understanding how to add new platform support

• crossbeam-rs/crossbeam — Provides additional concurrent data structures (channels, queues, epochs) built on top of parking_lot's primitives for Rust's concurrency ecosystem
• tokio-rs/tokio — Async runtime that depends on parking_lot for efficient blocking synchronization when interfacing with sync code
• rayon-rs/rayon — Data-parallel library that uses parking_lot internally for lightweight thread pool synchronization
• serde-rs/serde — parking_lot implements Serialize/Deserialize guards via serde feature flag, allowing lock-guarded values to serialize

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive benchmarking suite to CI with regression detection

The repo has a benchmark/ directory with mutex.rs and rwlock.rs but no CI workflow to track performance regressions across commits. Given that parking_lot emphasizes performance (1.5-5x faster claims in README), adding automated benchmark runs to rust.yml would catch performance regressions early. This is critical for a synchronization primitives library where performance is a core value proposition.

• [ ] Extend .github/workflows/rust.yml to include benchmark runs on key platforms (x86_64, potentially aarch64)
• [ ] Store benchmark results and compare against baseline to detect regressions
• [ ] Add benchmark execution for both benchmark/src/bin/mutex.rs and benchmark/src/bin/rwlock.rs
• [ ] Document benchmark setup in a new BENCHMARKING.md or update README with performance testing instructions

Add platform-specific unit tests for thread_parker implementations

The repo has 7 thread_parker implementations (linux.rs, windows/, unix.rs, wasm.rs, wasm_atomic.rs, redox.rs, sgx.rs, generic.rs) in core/src/thread_parker/ but tests/issue_203.rs and tests/issue_392.rs only test high-level issues. There are no targeted tests verifying each platform's parker works correctly, especially for less common platforms like redox, sgx, and wasm variants.

• [ ] Create tests/thread_parker_unix.rs to verify unix.rs parker implementation (park/unpark semantics)
• [ ] Create tests/thread_parker_windows.rs to test both keyed_event.rs and waitaddress.rs fallback paths
• [ ] Create tests/thread_parker_wasm.rs to verify both wasm.rs and wasm_atomic.rs implementations work correctly
• [ ] Add conditional compilation attributes so tests only run on appropriate platforms
• [ ] Test edge cases: multiple unpark before park, unpark after park, stressed scenarios with many threads

Add feature flag documentation and examples for deadlock_detection and send_guard

The Cargo.toml defines features like deadlock_detection, send_guard, and hardware-lock-elision but there's no documentation explaining when/why to use each, what the performance/safety tradeoffs are, or example code. New contributors and users cannot determine which features to enable. Add specific docs for src/deadlock.rs and the send_guard feature.

• [ ] Create or expand docs/FEATURES.md documenting deadlock_detection feature, when to use it, performance impact, and example code
• [ ] Add documentation comments to src/deadlock.rs explaining the deadlock detection mechanism and its limitations
• [ ] Document send_guard feature in docs/FEATURES.md explaining why it exists and safety implications
• [ ] Document hardware-lock-elision in src/elision.rs with example of when it helps vs hurts
• [ ] Add feature examples to README or new examples/ directory showing recommended feature combinations for different use cases

• Add comprehensive docstring examples to lock_api/src/lib.rs trait definitions (RawMutex, RawRwLock, RawReentrantMutex) showing how to implement a custom synchronization primitive—currently sparse examples make it hard for new contributors to understand the extension API.
• Expand benchmark/src/bin/mutex.rs and rwlock.rs with scenario-based benches (high contention, mixed read/write, long critical sections) and document expected speedup ratios vs std::sync—current benchmarks are minimal.
• Add integration tests in a new tests/ directory that verify Condvar requeue behavior under stress (e.g., notify_all only wakes 1 waiter, rest requeue to Mutex)—currently hard to validate this key feature works correctly.

The parking_lot codebase demonstrates strong security posture for a synchronization primitives library. No critical or high-severity vulnerabilities were identified. The library uses minimal external dependencies (only internal path dependencies and dev-only rand), reducing supply chain risk. Code complexity exists primarily in platform-specific OS integration code, which is appropriate for a low-level concurrency library. The project maintains good security practices including: dual licensing (MIT/Apache-2.0), active maintenance (Rust 1.84 MSRV), CI/CD pipeline integration, and structured release management. Main recommendations focus on continued periodic security audits of OS-specific FFI code and routine dependency vulnerability scanning.

• Low · Permissive MSRV (Minimum Supported Rust Version) — Cargo.toml - rust-version = "1.84". The crate supports Rust 1.84 which is a relatively recent version. While not a vulnerability per se, older MSRV targets may have contained security vulnerabilities in the Rust compiler itself. However, supporting recent versions is generally a positive security practice. Fix: Continue monitoring Rust compiler security updates and consider documented MSRV policy. Current version appears reasonable.
• Low · Platform-Specific Code Complexity — core/src/thread_parker/ (multiple OS-specific modules). The codebase includes platform-specific implementations for thread parking across multiple operating systems (Linux, Windows, macOS/Unix, WebAssembly, SGX, Redox). This increases the attack surface for OS-specific vulnerabilities. The Windows implementation includes complex FFI bindings to system APIs. Fix: Ensure all platform-specific FFI code has been thoroughly audited, particularly Windows bindings. Maintain up-to-date documentation of OS-level API usage and security considerations. Consider periodic third-party security audits for critical platform code.
• Low · Development Dependency: rand Crate — Cargo.toml - [dev-dependencies] rand = "0.8.3". The benchmark suite includes 'rand' as a dev-dependency. While dev-dependencies are lower risk, ensure the version 0.8.3 is actively maintained and has no known vulnerabilities. Fix: Verify rand 0.8.3 has no CVEs. Consider using cargo audit regularly to check dev-dependencies for vulnerabilities.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.