Arc<Mutex>

Guides

Rust walkthroughs

← Back to all guides

What are the trade-offs between dashmap::DashMap::shards and custom shard configuration for concurrency tuning?

DashMap::shards() provides access to the default number of shards (determined at compile time based on available parallelism), while custom shard configuration via DashMap::with_shards() allows explicit control over the shard count—tuning the trade-off between lock contention under high concurrency versus memory overhead from maintaining separate hash tables for each shard. The optimal shard count depends on your workload characteristics: number of concurrent threads, access patterns (read-heavy vs write-heavy), key distribution, and total data size.

The Sharding Architecture

use dashmap::DashMap;
use std::collections::HashMap;
 
fn sharding_architecture() {
    // DashMap is a concurrent hash map that achieves thread safety
    // through sharding: dividing data into N independent shards
    
    // Each shard is its own RwLock<HashMap<K, V>>
    // Operations lock only the relevant shard, not the entire map
    
    // This is fundamentally different from:
    // - RwLock<HashMap>: One lock for entire map
    // - ConcurrentHashMap in Java: Similar sharding approach
    
    let map: DashMap<String, i32> = DashMap::new();
    
    // DashMap::new() uses default shard count
    // Default: number of CPU cores (available parallelism)
    // This is usually good, but not always optimal
}

DashMap achieves concurrency through sharding—each shard has its own lock, allowing concurrent access to different shards.

Default Shard Count

use dashmap::DashMap;
 
fn default_shards() {
    let map: DashMap<String, i32> = DashMap::new();
    
    // shards() returns the number of shards
    let num_shards = map.shards();
    
    // Default is based on available parallelism
    // On an 8-core machine, this would be 8 or 16 shards
    // The actual formula: next_power_of_two(num_cpus * 4) typically
    
    println!("Number of shards: {}", num_shards);
    
    // The default is chosen to:
    // 1. Minimize contention for typical workloads
    // 2. Scale reasonably with hardware
    // 3. Not waste memory on machines with few cores
}

The default shard count is computed at compile time based on available parallelism.

Custom Shard Configuration

use dashmap::DashMap;
 
fn custom_shard_count() {
    // Use with_shards() to set a custom number of shards
    // Must be a power of 2
    
    // Small number of shards (less memory, more contention)
    let small_map: DashMap<String, i32> = DashMap::with_shards(4);
    
    // Large number of shards (more memory, less contention)
    let large_map: DashMap<String, i32> = DashMap::with_shards(256);
    
    // The with_shards() method takes a usize
    // It rounds up to the next power of 2
    
    assert_eq!(small_map.shards(), 4);
    assert_eq!(large_map.shards(), 256);
    
    // Shard count must be >= 1
    // let invalid = DashMap::<String, i32>::with_shards(0);  // Panics
}

with_shards() allows explicit control over shard count for specific workload tuning.

Shard Count and Concurrency

use dashmap::DashMap;
use std::thread;
 
fn shard_count_concurrency() {
    // Shard count affects how many threads can operate concurrently
    
    // With 4 shards:
    let map4: DashMap<String, i32> = DashMap::with_shards(4);
    
    // Only 4 threads can hold locks simultaneously (one per shard)
    // If all threads access the same shard, they serialize
    
    // With 256 shards:
    let map256: DashMap<String, i32> = DashMap::with_shards(256);
    
    // Up to 256 threads can operate concurrently
    // (assuming uniform key distribution)
    
    // But: more shards = more memory overhead
    // Each shard is a separate HashMap with its own allocation
    
    // Rule of thumb:
    // - Fewer threads than shards: contention likely low
    // - More threads than shards: contention increases
}

The shard count determines the maximum number of concurrent operations on different keys.

Memory Overhead Analysis

use dashmap::DashMap;
use std::mem::size_of;
 
fn memory_overhead() {
    // Each shard has overhead:
    // 1. HashMap structure (buckets, entries, etc.)
    // 2. RwLock for synchronization
    // 3. Separate memory allocation
    
    // Empty DashMap with 4 shards
    let map4: DashMap<String, i32> = DashMap::with_shards(4);
    
    // Empty DashMap with 256 shards
    let map256: DashMap<String, i32> = DashMap::with_shards(256);
    
    // The 256-shard map uses more memory even when empty
    // Each shard allocates its own HashMap structure
    
    // For small maps, this overhead is significant
    // For large maps, overhead is amortized
    
    // Rough memory comparison:
    // - Base HashMap overhead: ~48-64 bytes per shard
    // - 4 shards: ~200-250 bytes overhead
    // - 256 shards: ~12-16 KB overhead
    
    // For a map with millions of entries, 256 shards is fine
    // For a map with 10 entries, 256 shards is wasteful
}

Each shard adds memory overhead; high shard counts are wasteful for small datasets.

Contention and Key Distribution

use dashmap::DashMap;
use std::hash::{Hash, Hasher};
use std::collections::hash_map::DefaultHasher;
 
fn key_distribution() {
    // DashMap uses key hashing to determine shard
    
    // Shard = hash(key) % num_shards
    // Keys are distributed across shards based on hash
    
    // With good hash distribution, keys spread evenly
    let map: DashMap<String, i32> = DashMap::with_shards(16);
    
    // But with poor hash distribution or specific key patterns:
    
    // Example: Keys that hash to same shard
    // This causes "hot shard" problem
    // All operations go to same shard, serializing
    
    // The shard count should match your key distribution:
    // - Random/well-distributed keys: any shard count works
    // - Sequential keys (i1, i2, i3...): depends on hash function
    // - Clustered keys: might need more shards to spread load
    
    fn which_shard<K: Hash>(key: &K, num_shards: usize) -> usize {
        let mut hasher = DefaultHasher::new();
        key.hash(&mut hasher);
        let hash = hasher.finish();
        (hash % num_shards as u64) as usize
    }
    
    // Check distribution for your keys
    let shard = which_shard(&"hello".to_string(), 16);
    println!("Key 'hello' maps to shard {}", shard);
}

Keys are mapped to shards via hashing; uneven distribution causes hot shards.

Read-Heavy vs Write-Heavy Workloads

use dashmap::DashMap;
 
fn workload_patterns() {
    // DashMap uses RwLock per shard
    // RwLock allows multiple readers OR one writer
    
    // Read-heavy workloads benefit from:
    // - Fewer shards (reads don't block each other)
    // - More memory efficiency
    
    // Write-heavy workloads benefit from:
    // - More shards (writes only block same shard)
    // - Better concurrency under contention
    
    // Example: Mostly reads, few writes
    // Use fewer shards
    let read_heavy: DashMap<String, i32> = DashMap::with_shards(8);
    
    // Many threads reading: RwLock allows concurrent reads
    // Occasional write: blocks one shard briefly
    
    // Example: Many writes, high contention
    // Use more shards
    let write_heavy: DashMap<String, i32> = DashMap::with_shards(64);
    
    // Writers spread across shards
    // Less likely to block each other
    
    // The optimal balance depends on your read/write ratio
}

DashMap uses RwLock per shard; read-heavy workloads tolerate fewer shards better than write-heavy ones.

Benchmarking Shard Count

use dashmap::DashMap;
use std::thread;
use std::time::Instant;
 
fn benchmark_shards() -> usize {
    // Pseudo-benchmark to find optimal shard count
    let shard_counts = [4, 8, 16, 32, 64, 128];
    let num_threads = 16;
    let ops_per_thread = 100_000;
    
    let mut best_count = 4;
    let mut best_time = u64::MAX;
    
    for &count in &shard_counts {
        let start = Instant::now();
        
        let map: DashMap<u64, u64> = DashMap::with_shards(count);
        
        let handles: Vec<_> = (0..num_threads)
            .map(|tid| {
                let map = map.clone();
                thread::spawn(move || {
                    for i in 0..ops_per_thread {
                        let key = (tid * ops_per_thread + i) as u64;
                        map.insert(key, i as u64);
                    }
                })
            })
            .collect();
        
        for handle in handles {
            handle.join().unwrap();
        }
        
        let elapsed = start.elapsed().as_nanos() as u64;
        if elapsed < best_time {
            best_time = elapsed;
            best_count = count;
        }
        
        println!("Shards: {}, Time: {} ns", count, elapsed);
    }
    
    // This is a simplified benchmark
    // Real tuning requires:
    // 1. Your actual key distribution
    // 2. Your actual access patterns
    // 3. Your actual data size
    
    best_count
}

The optimal shard count depends on your specific workload; benchmark with real access patterns.

When to Use More Shards

use dashmap::DashMap;
 
fn more_shards_beneficial() {
    // More shards are beneficial when:
    
    // 1. High write contention
    // Many threads writing to different keys
    let high_contention: DashMap<String, i32> = DashMap::with_shards(128);
    
    // 2. Large number of threads
    // More threads than default shards
    // Default might be 16, but you have 64 threads
    let many_threads: DashMap<String, i32> = DashMap::with_shards(64);
    
    // 3. Large dataset
    // Memory overhead of extra shards is amortized
    let large_dataset: DashMap<u64, Vec<u8>> = DashMap::with_shards(256);
    
    // 4. Non-uniform key distribution
    // Some keys are hotter, need more shards to spread them
    let skewed_keys: DashMap<String, i32> = DashMap::with_shards(64);
    
    // 5. Latency-sensitive operations
    // Want to minimize time spent waiting for locks
    let low_latency: DashMap<String, i32> = DashMap::with_shards(128);
}

More shards help when write contention, thread count, or dataset size is high.

When to Use Fewer Shards

use dashmap::DashMap;
 
fn fewer_shards_beneficial() {
    // Fewer shards are beneficial when:
    
    // 1. Read-heavy workload
    // RwLock allows concurrent reads, contention is low
    let read_heavy: DashMap<String, i32> = DashMap::with_shards(4);
    
    // 2. Small dataset
    // Memory overhead of many shards is significant
    let small_map: DashMap<String, i32> = DashMap::with_shards(4);
    
    // 3. Few threads
    // No need for many shards if few threads are accessing
    let few_threads: DashMap<String, i32> = DashMap::with_shards(4);
    
    // 4. Memory-constrained environment
    // Each shard allocates memory for HashMap structure
    let memory_constrained: DashMap<String, i32> = DashMap::with_shards(4);
    
    // 5. Sequential access patterns
    // Single thread or coordinated access, no contention
    let sequential: DashMap<String, i32> = DashMap::with_shards(1);
    // Note: Even with 1 shard, DashMap still provides thread safety
    // It's just a RwLock<HashMap> in this case
}

Fewer shards are appropriate for read-heavy workloads, small datasets, or memory-constrained environments.

The Shards() Method

use dashmap::DashMap;
 
fn shards_method() {
    let map: DashMap<String, i32> = DashMap::new();
    
    // shards() returns the number of shards
    let num_shards = map.shards();
    
    // This is useful for:
    // 1. Logging/debugging
    println!("DashMap has {} shards", num_shards);
    
    // 2. Metrics/monitoring
    // Track shard utilization
    // If one shard is much larger, consider different keys or more shards
    
    // 3. Calculating expected contention
    let num_threads = 8;
    let contention_ratio = num_threads as f64 / num_shards as f64;
    println!("Contention ratio: {:.2}", contention_ratio);
    
    // 4. Verifying configuration
    let custom_map: DashMap<String, i32> = DashMap::with_shards(32);
    assert!(custom_map.shards() >= 32);  // May be rounded to next power of 2
}

shards() returns the current shard count, useful for monitoring and debugging.

Shard Internals

use dashmap::DashMap;
 
fn shard_internals() {
    // Each DashMap contains:
    // - Vector of shards (shard_count elements)
    // - Each shard is: Arc<RwLock<HashMap<K, V>>>
    // - Hasher for determining shard
    
    let map: DashMap<String, i32> = DashMap::with_shards(16);
    
    // When you insert:
    // 1. Hash the key
    // 2. Determine shard: hash % num_shards
    // 3. Lock that shard (write lock)
    // 4. Insert into that shard's HashMap
    // 5. Unlock
    
    // When you read:
    // 1. Hash the key
    // 2. Determine shard: hash % num_shards
    // 3. Lock that shard (read lock)
    // 4. Look up in that shard's HashMap
    // 5. Unlock
    
    // When you iterate:
    // 1. Lock all shards (read locks)
    // 2. Iterate through all HashMaps
    // 3. Unlock all
    
    // The per-shard RwLock provides:
    // - Multiple concurrent readers per shard
    // - Exclusive writer per shard
    // - Independent locking between shards
}

Each shard is a RwLock<HashMap>; operations hash the key to find the appropriate shard.

Accessing Individual Shards

use dashmap::DashMap;
 
fn shard_access() {
    let map: DashMap<String, i32> = DashMap::with_shards(16);
    
    // You can access shards individually for advanced operations
    
    // shards() returns &Vec<RwLock<HashMap<K, V>>>
    // (through a shard iterator or internal structure)
    
    // For most operations, you don't need direct shard access
    // DashMap handles it internally
    
    // But you can implement custom logic:
    
    // Example: Find which shard a key would be in
    use std::hash::{Hash, Hasher};
    use std::collections::hash_map::DefaultHasher;
    
    fn shard_for_key<K: Hash>(key: &K, num_shards: usize) -> usize {
        let mut hasher = DefaultHasher::new();
        key.hash(&mut hasher);
        (hasher.finish() as usize) % num_shards
    }
    
    let key = "hello".to_string();
    let shard_idx = shard_for_key(&key, map.shards());
    println!("Key '{}' is in shard {}", key, shard_idx);
    
    // This is useful for:
    // - Debugging hot spots
    // - Custom sharding strategies
    // - Metrics per shard
}

Understanding shard mapping helps debug contention and analyze key distribution.

Comparison: Default vs Custom Shards

use dashmap::DashMap;
use std::sync::Arc;
use std::thread;
 
fn default_vs_custom_comparison() {
    // Scenario 1: Default (number of CPU cores)
    let default_map: DashMap<String, i32> = DashMap::new();
    println!("Default shards: {}", default_map.shards());
    
    // Pros: Good general-purpose choice
    // - Scales with hardware
    // - Reasonable memory overhead
    // - Works well for typical workloads
    
    // Cons: May not be optimal for specific cases
    // - High contention: may need more shards
    // - Small maps: may waste memory
    // - Special patterns: may need tuning
    
    // Scenario 2: Custom (tuned for workload)
    // High contention, many threads
    let tuned_high: DashMap<String, i32> = DashMap::with_shards(64);
    
    // Small map, few threads
    let tuned_low: DashMap<String, i32> = DashMap::with_shards(4);
    
    // Benchmark results typically show:
    // - Default: Good baseline, acceptable for most cases
    // - Tuned: 10-30% better for specific workloads
    // - Over-tuned: Diminishing returns, wasted memory
}

Default sharding works well for most cases; custom tuning provides marginal improvements for specific workloads.

Real-World Tuning Example

use dashmap::DashMap;
use std::time::Instant;
 
fn real_world_tuning() {
    // Scenario: Web server cache with 1000 concurrent connections
    // Key: User session ID (UUID)
    // Value: Session data
    // Access pattern: Read-heavy (95% reads, 5% writes)
    
    // Option 1: Default (let's say 16 cores -> ~16 shards)
    let default_cache: DashMap<String, Session> = DashMap::new();
    
    // Option 2: Custom based on analysis
    // 1000 connections, but reads dominate
    // RwLock allows concurrent reads, so fewer shards OK
    // But session creation (writes) happen on login, could be bursty
    let tuned_cache: DashMap<String, Session> = DashMap::with_shards(32);
    
    // Analysis:
    // - Read-heavy: RwLock handles concurrent reads well
    // - Bursty writes: More shards help during login storms
    // - Medium dataset: Memory overhead of 32 shards acceptable
    // - 1000 connections: 32 shards gives good distribution
    
    // Decision: Custom 32 shards
    // - 2x typical core count
    // - Handles write bursts
    // - Memory overhead minimal for session data
}
 
struct Session {
    user_id: u64,
    created: Instant,
    data: Vec<u8>,
}

Real-world tuning considers access patterns, thread count, and data characteristics.

Shard Count and Iteration

use dashmap::DashMap;
 
fn iteration_impact() {
    let map: DashMap<u64, String> = DashMap::with_shards(256);
    
    // Fill map
    for i in 0..10000 {
        map.insert(i, format!("value_{}", i));
    }
    
    // Iteration locks ALL shards
    // More shards = more locks to acquire
    
    // Example: Iterating with many shards
    let start = std::time::Instant::now();
    let count = map.iter().count();
    println!("Count: {}, Time: {:?}", count, start.elapsed());
    
    // This acquires read locks on all 256 shards
    // For iteration-heavy workloads, fewer shards may be better
    
    // Alternative: Access shards individually
    // (Not directly exposed, but conceptually)
    
    // For iteration-heavy code:
    let iter_map: DashMap<u64, String> = DashMap::with_shards(4);
    // Fewer shards = faster iteration (fewer locks)
}

Iteration acquires locks on all shards; more shards mean more lock operations.

Memory Profiling

use dashmap::DashMap;
 
fn memory_profiling() {
    // Estimate memory usage for different shard counts
    
    fn estimate_overhead(shards: usize, entries_per_shard: usize) -> usize {
        // Rough estimate:
        // - Each shard: HashMap overhead (~48-64 bytes empty)
        // - Each entry: key + value + HashMap overhead (~24 bytes for structure)
        
        let shard_overhead = shards * 64;
        let entry_overhead = shards * entries_per_shard * 24;
        
        shard_overhead + entry_overhead
    }
    
    // Small map: 1000 entries
    let small_4_shards = estimate_overhead(4, 250);
    let small_256_shards = estimate_overhead(256, 4);
    
    // 4 shards: 4 * 64 + 4 * 250 * 24 = 24,256 bytes overhead
    // 256 shards: 256 * 64 + 256 * 4 * 24 = 26,624 bytes overhead
    
    // Large map: 1,000,000 entries
    let large_4_shards = estimate_overhead(4, 250_000);
    let large_256_shards = estimate_overhead(256, 3_906);
    
    // 4 shards: 4 * 64 + 4 * 250000 * 24 = 24,000,256 bytes
    // 256 shards: 256 * 64 + 256 * 3906 * 24 = 24,009,728 bytes
    
    // The shard overhead becomes negligible for large maps
    
    println!("Small map overhead (4 shards): {} bytes", small_4_shards);
    println!("Small map overhead (256 shards): {} bytes", small_256_shards);
}

Shard overhead is significant for small maps but negligible for large ones.

Summary Table

fn summary() {
    // | Configuration | Memory Overhead | Contention | Iteration |
    // |---------------|-----------------|------------|-----------|
    // | Fewer shards  | Lower           | Higher     | Faster    |
    // | More shards   | Higher          | Lower      | Slower    |
    // | Default       | Medium          | Medium     | Medium    |
    
    // | Workload      | Recommended Shards |
    // |---------------|---------------------|
    // | Read-heavy    | Fewer (4-16)        |
    // | Write-heavy   | More (32-128)       |
    // | Mixed         | Default or 32-64    |
    // | Small data    | Fewer (4-16)        |
    // | Large data    | More (64-256)       |
    
    // | Factor        | Effect on Shard Count |
    // |---------------|----------------------|
    // | More threads  | Increase             |
    // | More data     | Increase acceptable  |
    // | More writes   | Increase             |
    // | More reads    | Decrease acceptable  |
    // | Memory limit  | Decrease             |
}

Synthesis

Quick reference:

use dashmap::DashMap;
 
// Default: uses available parallelism
let default_map: DashMap<K, V> = DashMap::new();
 
// Custom: specify shard count (must be power of 2)
let custom_map: DashMap<K, V> = DashMap::with_shards(32);
 
// Query current shard count
let shards = map.shards();
 
// Guidelines:
// - Read-heavy + small data: 4-16 shards
// - Write-heavy + large data: 64-256 shards
// - Many threads: ~thread count or higher
// - Memory constrained: fewer shards
// - When in doubt: use default

Key insight: The shard count in DashMap represents a fundamental trade-off between concurrency and memory overhead. More shards mean more concurrent operations can proceed without blocking, but each shard carries its own RwLock and HashMap allocation overhead. The default shard count (based on CPU cores) works well for typical workloads because it scales with available parallelism—more cores can handle more concurrent operations, so more shards makes sense. Custom shard configuration is valuable when your workload diverges significantly from this assumption: high write contention benefits from more shards to spread the locking load, while read-heavy or small-map workloads benefit from fewer shards to reduce memory overhead. The shards() method lets you inspect the current configuration for debugging and metrics. When tuning, measure your specific workload—key distribution, read/write ratio, and thread count all affect the optimal choice. Remember that sharding is about spreading contention, not just maximizing the number of shards; too many shards for a small dataset wastes memory without improving performance.