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/xacrimon/dashmap 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.

WAIT — Stale — last commit 1y ago

• 22+ active contributors
• MIT licensed
• CI configured
• ⚠ Stale — last commit 1y ago
• ⚠ Concentrated ownership — top contributor handles 61% of recent commits
• ⚠ No test directory detected

_{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 xacrimon/dashmap repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/xacrimon/dashmap.

What it runs against: a local clone of xacrimon/dashmap — 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 xacrimon/dashmap | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | 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 ≤ 458 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of xacrimon/dashmap. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/xacrimon/dashmap.git
#   cd dashmap
#
# 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 xacrimon/dashmap and re-run."
  exit 2
fi

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

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT 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 "src/lock.rs" \\
  && ok "src/lock.rs" \\
  || miss "missing critical file: src/lock.rs"
test -f "src/mapref/one.rs" \\
  && ok "src/mapref/one.rs" \\
  || miss "missing critical file: src/mapref/one.rs"
test -f "src/iter.rs" \\
  && ok "src/iter.rs" \\
  || miss "missing critical file: src/iter.rs"
test -f "src/rayon/map.rs" \\
  && ok "src/rayon/map.rs" \\
  || miss "missing critical file: src/rayon/map.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 458 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~428d)"
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/xacrimon/dashmap"
  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).

DashMap is a blazingly fast concurrent HashMap implementation for Rust that provides lock-free reads and fine-grained locking through sharding. It exposes an API similar to std::collections::HashMap but designed for multi-threaded scenarios, allowing all methods to take &self instead of &mut self so it can be safely shared across threads via Arc<T> without runtime overhead of RwLock<HashMap<K, V>>. Single-crate library with clear module separation: src/lib.rs is the entry point, core DashMap logic lives in the root, src/lock.rs handles synchronization primitives, src/mapref/ exports reference types (entry.rs, one.rs, multiple.rs) for borrowed access patterns, src/setref/ mirrors these for the Set variant. Optional features add src/serde.rs (serialization), src/rayon/ (parallel iteration), src/arbitrary.rs (property testing). Sharding strategy is internal to achieve lock granularity.

Rust systems engineers and library developers building high-concurrency applications (databases, cache layers, message brokers) who need a drop-in replacement for RwLock<HashMap<K, V>> with much better throughput and latency characteristics, particularly those targeting sub-microsecond access patterns.

Actively maintained and production-ready. At version 7.0.0-rc2 with MSRV 1.70 that is conservatively maintained (staying 1 year behind stable). The codebase is well-structured with optional features (serde, rayon, raw-api), CI/CD pipeline via .github/workflows/ci.yml, and comprehensive test coverage. However, as a release candidate, the exact 7.0 API is still settling.

Low risk for consumption but moderate single-maintainer dependency risk: Joel Wejdenstål is the primary author with limited paid time allocation. The 7.0-rc2 tag indicates API changes are still possible. Dependency surface is lean (lock_api, parking_lot_core, hashbrown, crossbeam-utils) with well-vetted crates. No visible red flags in open issues from the provided data, but the MSRV constraint (1.70) may restrict adoption in legacy codebases.

Transitioning toward 7.0 release (currently rc2). The codebase reflects recent stabilization efforts with organized mapref/setref module structure and typesize dependency for memory introspection. Rayon integration indicates active work on parallel iteration APIs. No specific PR or milestone data provided, but the rc tag suggests API polish and performance tuning are underway.

git clone https://github.com/xacrimon/dashmap && cd dashmap && cargo test && cargo doc --open

Daily commands: No server to run. For library: add to Cargo.toml dashmap = "7.0". For development: cargo test runs the test suite, cargo bench runs benchmarks (if defined), cargo doc --open generates API documentation.

• src/lib.rs — Main entry point exposing the DashMap API; defines the core HashMap struct, all public methods, and feature gates.
• src/lock.rs — Wrapper around parking_lot's synchronization primitives; critical for understanding how DashMap achieves low-contention locking.
• src/mapref/one.rs — Reference guard for single-entry access; essential for understanding the borrow-checker-friendly API that returns Ref/RefMut instead of &/&mut.
• src/iter.rs — Iterator implementation over the map; shows how DashMap handles concurrent iteration without blocking.
• src/rayon/map.rs — Rayon parallel iteration support; demonstrates how DashMap integrates with parallel processing frameworks.
• Cargo.toml — Dependency manifest; reveals key dependencies (parking_lot_core, hashbrown) that enable DashMap's concurrent performance.

• DashMap<K, V> ( — undefined

Add a new public method to DashMap

1. Define the method signature in the impl block in src/lib.rs (typically following existing patterns like insert, get, remove). Use &self for concurrent access. (src/lib.rs)
2. If the method returns per-entry references, create new Ref/RefMut types in src/mapref/one.rs or use existing ones. (src/mapref/one.rs)
3. For complex reference patterns (multiple entries), extend src/mapref/multiple.rs. (src/mapref/multiple.rs)
4. Mirror the method in DashSet in src/set.rs by delegating to DashMap. (src/set.rs)
5. If the method is iterable, update src/iter.rs to support the new pattern if needed. (src/iter.rs)

Enable a new optional feature

1. Add the feature gate in Cargo.toml [features] section and list its dependency in [dependencies]. (Cargo.toml)
2. Create or update the implementation file (e.g., src/serde.rs for serialization) with #[cfg(feature = "...")]. (src/serde.rs)
3. Re-export or conditionally compile integration points in src/lib.rs using #[cfg(feature = "...")]. (src/lib.rs)
4. Add feature to the 'all' meta-feature in Cargo.toml. (Cargo.toml)

Add parallel iteration support for a new wrapper type

1. Create a new file in src/rayon/ (e.g., src/rayon/custom.rs) implementing ParallelIterator. (src/rayon/map.rs)
2. Follow the pattern in src/rayon/map.rs: wrap DashMap shards and implement ParallelIterator trait. (src/rayon/map.rs)
3. Wire the ParallelIterator impl into the wrapper type's impl block in src/lib.rs (conditional on rayon feature). (src/lib.rs)

• parking_lot_core RwLock — Provides faster, more space-efficient synchronization than std::sync::RwLock; fair reader-writer semantics with minimal overhead.
• hashbrown (external hash table) — High-performance, battle-tested hash implementation from the Rust core library; allows DashMap to focus on concurrency, not hash table internals.
• Shard-based partitioning — Divides the map into N independent locked shards, reducing lock contention under concurrent workloads compared to a single global lock.
• Reference guard RAII (Ref/RefMut) — Allows Arc<DashMap> shared ownership with &self mutations; return guards instead of & or &mut to hold locks across method boundaries.
• Rayon optional feature — Provides ParallelIterator support for leveraging multiple cores; optional to keep core dependency footprint small.

• All methods take &self instead of &mut self

  • Why: Enables Arc<DashMap<K,V>> for easy concurrent sharing across threads without interior mutability boilerplate.
  • Consequence: API differs from std::HashMap; users must use reference guards (Ref/RefMut) instead of direct & references, adding a small cognitive load.

• Fixed number of shards (default ~16) partitioning

  • Why: Reduces per-entry lock overhead and improves cache locality compared to fine-grained per-entry locks.
  • Consequence: On very high-contention workloads with hot keys in the same shard, contention is not eliminated—trades memory/complexity for typical performance gains.

• Iterator acquires per-bucket locks, not whole-map lock

  • Why: Allows concurrent inserts/removes during iteration, improving real-world throughput.
  • Consequence: Iteration is not a snapshot; mutations may or may not be visible depending on iteration order, consistent with concurrent semantics.

• Serde/Rayon/Arbitrary as optional features

  • Why: Keeps default build lean; users only pay for what they use.
  • Consequence: Increased build complexity; some ecosystem integrations require explicit feature flags.

• Does not provide transactional semantics or ACID guarantees across multiple keys.
• Does not support custom hash functions or key ordering (provides sensible defaults only).
• Does not handle distributed/remote scenarios; single-machine concurrent only.
• Does not provide weak references or entry versioning for tracking stale handles.

MSRV is strictly enforced at 1.70 via rust-toolchain.toml; features like parking_lot_core 0.9.10 have platform-specific behavior on exotic architectures. The raw-api feature is explicitly unstable per Cargo.toml. Serde support requires opt-in; data structures are not serializable by default. DashMap does not provide transactional semantics across multiple operations (no atomic CAS across keys), so check-then-act patterns require external coordination. The sharding strategy is deterministic but internal; user code cannot customize shard count.

• Sharded Locking — DashMap's core performance trick—dividing the map into independent sharded buckets with per-shard locks instead of one global lock, dramatically reducing contention in concurrent workloads
• Lock-free Read Optimization — DashMap uses techniques like RCU (read-copy-update) patterns and minimal-cost read barriers to allow concurrent readers without mutual exclusion, critical for read-heavy workloads
• Parking Lot Synchronization — DashMap's synchronization strategy relies on parking_lot_core, which uses kernel-level parking instead of busy-waiting, providing lower latency and CPU overhead than std::sync::Mutex
• Entry API Pattern — DashMap exposes Vacant and Occupied entry types (src/mapref/entry.rs) enabling safe, efficient upsert patterns without double-lookups; critical for implementing idiomatic Rust concurrent algorithms
• Guard-based Reference Borrowing — Ref and RefMut types (src/mapref/one.rs) hold locks during scope via RAII; essential for understanding when locks are released and how to avoid deadlocks in concurrent code
• Hashbrown Integration — DashMap is built on hashbrown (a more optimized HashMap than std), understanding its memory layout and bucket organization is necessary for custom hashing or performance tuning
• Arbitrary Trait for Property Testing — The optional arbitrary feature (src/arbitrary.rs) enables property-based testing of concurrent algorithms; useful for validating correctness under randomized workloads

• crossbeam-rs/crossbeam — Provides crossbeam-utils (a DashMap dependency) and alternative concurrent data structures; ecosystem foundation for fine-grained concurrency primitives
• parking_lot-rs/parking_lot — DashMap wraps parking_lot_core for efficient synchronization; understanding parking_lot is essential for grasping DashMap's performance characteristics
• rust-lang/hashbrown — Upstream hash table implementation that DashMap layers concurrency on top of; critical dependency for understanding the core data structure
• rayon-rs/rayon — Enables the optional rayon feature for parallel iteration; complementary for bulk DashMap operations in data-parallel scenarios
• tikv/dashmap — Historical predecessor and inspiration; TiKV's fork may have alternative concurrency strategies or performance tuning useful for comparison

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 benchmarks for entry API and ref-counting overhead

The repo has mapref/entry.rs and mapref/entry_ref.rs but lacks dedicated benchmarks comparing performance of entry() vs get() vs get_mut() operations. Given DashMap's focus on being 'blazingly fast', benchmarking the entry API (which is more complex than direct access) would reveal performance characteristics and help contributors optimize or document trade-offs. This is especially important for the two entry reference implementations.

• [ ] Create benches/ directory if it doesn't exist
• [ ] Add benchmarks comparing mapref::entry::Entry vs direct get/insert patterns
• [ ] Add benchmarks for mapref::entry_ref::EntryRef to measure ref-counting overhead
• [ ] Add benchmarks comparing single vs multiple entry operations (src/mapref/multiple.rs)
• [ ] Document results in a BENCHMARKS.md file

Add integration tests for rayon parallel iterators with real-world patterns

The src/rayon/ directory (map.rs, read_only.rs, set.rs) provides parallel iteration support, but there are likely no dedicated integration tests verifying correctness under concurrent modification patterns. Add tests validating that rayon-based operations maintain consistency when used with typical parallel workloads (e.g., map-reduce patterns, aggregation operations).

• [ ] Create tests/rayon_integration.rs if it doesn't exist
• [ ] Add tests for concurrent modifications during rayon::map() iteration
• [ ] Add tests for rayon::read_only() isolation and snapshot consistency
• [ ] Add tests for rayon::set() operations with large concurrent workloads
• [ ] Add tests validating deterministic results across multiple runs

Add feature-gated miri and sanitizer CI checks in ci.yml

The .github/workflows/ci.yml exists but likely lacks memory safety checks for a concurrent data structure library. Add miri (interpreter for Rust) and address/thread sanitizer runs to catch subtle concurrency bugs. This is critical for a HashMap focusing on correctness under concurrent access patterns.

• [ ] Update .github/workflows/ci.yml to add miri test job with --lib and --doc flags
• [ ] Add thread sanitizer (TSAN) job for unsafe code validation in src/lock.rs
• [ ] Add address sanitizer (ASAN) job to detect memory errors
• [ ] Configure miri to ignore false positives from parking_lot_core
• [ ] Document new checks in CONTRIBUTING.md

• Add comprehensive benchmarks comparing DashMap against parking_lot RwLock<HashMap> and crossbeam Dashmap alternatives in src/benches/ or examples/, particularly for write-heavy and read-heavy workloads to validate marketing claims
• Expand src/serde.rs test coverage to ensure round-trip serialization/deserialization for all key types (custom structs, enums) and add documentation examples showing serde usage patterns
• Document the Entry API (src/mapref/entry.rs) with concrete examples showing Vacant/Occupied patterns for beginners; create examples/entry_api.rs demonstrating counter upsert, conditional insert, and safe remove patterns

DashMap demonstrates a strong security posture overall. It is a well-maintained Rust concurrent data structure library with no critical vulnerabilities identified in the static analysis. The codebase lacks injection risks (no SQL, web, or serialization endpoints), hardcoded secrets, or infrastructure misconfigurations. Minor improvements recommended include implementing dependency vulnerability scanning in CI/CD, adding stricter version constraints for critical dependencies, and enhancing documentation around the 'raw-api' feature's safety requirements. The project maintains a conservative MSRV (1.70) and uses well-established, actively maintained dependencies from the Rust ecosystem.

• Low · Dependency Version Constraints Not Pinned — Cargo.toml - dependencies section. Several dependencies use non-pinned version specifiers (e.g., parking_lot_core = "0.9.10", lock_api = "0.4.12"). While not critical, this allows for patch and minor version updates that could introduce unexpected behavioral changes or vulnerabilities. Fix: Consider using more restrictive version constraints (e.g., "=0.4.12" for critical dependencies) or implement dependency scanning in CI/CD pipeline to monitor for vulnerabilities in transitive dependencies.
• Low · Optional Feature 'raw-api' Without Clear Security Boundaries — Cargo.toml - [features] section and src/lib.rs. The 'raw-api' feature is enabled via the 'all' meta-feature without clear documentation of safety implications. Raw API access to concurrent data structures can lead to unsafe usage patterns if consumers don't understand thread-safety guarantees. Fix: Add comprehensive documentation to the raw-api feature explaining the safety requirements and constraints. Consider adding compile-time warnings or runtime checks for unsafe usage patterns.
• Low · Missing Dependency Audit in CI/CD Pipeline — .github/workflows/ci.yml. No evidence of cargo-audit or similar security scanning tools in the CI configuration file (.github/workflows/ci.yml) to detect known vulnerabilities in dependencies. Fix: Integrate cargo audit or RUSTSEC scanning into the CI/CD pipeline to automatically detect and alert on known security vulnerabilities in dependencies.

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.