Arc<Mutex>

Guides

Rust walkthroughs

← Back to all guides

What is the purpose of rayon::ThreadPoolBuilder::num_threads for customizing parallelism levels?

Rayon's ThreadPoolBuilder::num_threads configures the number of worker threads in a custom thread pool, giving precise control over parallelism levels. By default, Rayon creates a global thread pool with one thread per CPU core, but many workloads benefit from customizing this number—limiting threads for resource-constrained environments, reserving cores for other tasks, or matching thread count to workload characteristics. Understanding when and how to adjust thread counts enables optimal resource utilization and prevents oversubscription in complex systems.

Default Thread Pool Behavior

use rayon::prelude::*;
 
fn default_parallelism() {
    let data = (0..1_000_000).collect::<Vec<_>>();
    
    // Uses global thread pool with threads = CPU cores
    let sum: i64 = data.par_iter().sum();
    
    println!("Sum: {}", sum);
}

The global thread pool automatically uses one thread per available CPU core.

Configuring Thread Count

use rayon::ThreadPoolBuilder;
 
fn custom_thread_count() -> Result<(), rayon::ThreadPoolBuildError> {
    let pool = ThreadPoolBuilder::new()
        .num_threads(4)
        .build()?;
    
    pool.install(|| {
        let data = (0..1_000_000).collect::<Vec<_>>();
        let sum: i64 = data.par_iter().sum();
        println!("Sum: {}", sum);
    });
    
    Ok(())
}

num_threads(4) creates a pool with exactly four worker threads regardless of CPU core count.

Why Customize Thread Count

use rayon::ThreadPoolBuilder;
 
fn limited_threads() -> Result<(), rayon::ThreadPoolBuildError> {
    // Scenario 1: Running alongside other services
    let pool = ThreadPoolBuilder::new()
        .num_threads(2) // Reserve cores for other services
        .build()?;
    
    // Scenario 2: Memory-constrained environment
    // Each thread has its own stack, reducing threads saves memory
    let memory_pool = ThreadPoolBuilder::new()
        .num_threads(2)
        .build()?;
    
    // Scenario 3: I/O-bound work doesn't need many threads
    let io_pool = ThreadPoolBuilder::new()
        .num_threads(8) // Modest parallelism for I/O
        .build()?;
    
    Ok(())
}

Custom thread counts adapt to resource constraints and workload characteristics.

Global Thread Pool Configuration

use rayon::ThreadPoolBuilder;
 
fn configure_global_pool() -> Result<(), rayon::ThreadPoolBuildError> {
    // Configure the global thread pool at startup
    ThreadPoolBuilder::new()
        .num_threads(8)
        .build_global()?;
    
    // All parallel iterators use this pool by default
    let data = (0..1_000_000).collect::<Vec<_>>();
    let sum: i64 = data.par_iter().sum();
    
    Ok(())
}

build_global() sets the thread count for the default global pool.

Thread Count vs CPU Cores

use rayon::ThreadPoolBuilder;
use std::env;
 
fn adaptive_thread_count() -> Result<(), rayon::ThreadPoolBuildError> {
    let cpu_count = num_cpus::get();
    
    // Use fewer threads than cores to leave room for other work
    let worker_threads = (cpu_count / 2).max(1);
    
    let pool = ThreadPoolBuilder::new()
        .num_threads(worker_threads)
        .build()?;
    
    // Or use more threads than cores for I/O-bound work
    let io_threads = cpu_count * 2;
    
    let io_pool = ThreadPoolBuilder::new()
        .num_threads(io_threads)
        .build()?;
    
    Ok(())
}

Thread count can be higher or lower than CPU cores depending on workload type.

Nested Parallelism with Multiple Pools

use rayon::{ThreadPool, ThreadPoolBuilder};
 
fn nested_parallelism() -> Result<(), rayon::ThreadPoolBuildError> {
    // Outer pool with fewer threads
    let outer_pool = ThreadPoolBuilder::new()
        .num_threads(2)
        .build()?;
    
    // Inner pool with more threads
    let inner_pool = ThreadPoolBuilder::new()
        .num_threads(4)
        .build()?;
    
    outer_pool.install(|| {
        let data: Vec<Vec<i32>> = (0..100)
            .map(|i| (0..1000).map(|j| i * 1000 + j).collect())
            .collect();
        
        data.par_iter()
            .map(|chunk| {
                inner_pool.install(|| {
                    chunk.par_iter().sum::<i32>()
                })
            })
            .sum::<i32>()
    });
    
    Ok(())
}

Multiple pools enable different parallelism levels for different work phases.

Work Stealing and Thread Count

use rayon::ThreadPoolBuilder;
 
fn work_stealing_example() -> Result<(), rayon::ThreadPoolBuildError> {
    let pool = ThreadPoolBuilder::new()
        .num_threads(4)
        .build()?;
    
    pool.install(|| {
        // Rayon uses work stealing: idle threads steal from busy threads
        let data: Vec<i32> = (0..1_000_000).collect();
        
        // Uneven work distribution handled by work stealing
        data.par_iter()
            .map(|&x| {
                if x % 100 == 0 {
                    // Expensive computation
                    (0..1000).sum::<i32>()
                } else {
                    x
                }
            })
            .sum::<i32>()
    });
    
    Ok(())
}

Work stealing distributes load among threads, but fewer threads means less parallelism.

Memory Considerations

use rayon::ThreadPoolBuilder;
 
fn memory_usage() -> Result<(), rayon::ThreadPoolBuildError> {
    // Each thread has its own stack (typically 2MB by default)
    // 4 threads = ~8MB stack memory baseline
    
    // For memory-constrained environments:
    let pool = ThreadPoolBuilder::new()
        .num_threads(2)
        .stack_size(1024 * 1024) // 1MB stack per thread
        .build()?;
    
    // Total stack: 2MB instead of default ~8MB
    
    Ok(())
}

Fewer threads and smaller stacks reduce memory overhead.

CPU-Bound vs I/O-Bound Workloads

use rayon::ThreadPoolBuilder;
 
fn cpu_bound_threads() -> Result<(), rayon::ThreadPoolBuildError> {
    // CPU-bound: threads ≈ CPU cores
    let cpu_count = num_cpus::get();
    let cpu_pool = ThreadPoolBuilder::new()
        .num_threads(cpu_count)
        .build()?;
    
    cpu_pool.install(|| {
        (0..1_000_000)
            .into_par_iter()
            .map(|x| (x as f64).sin().cos())
            .sum::<f64>()
    });
    
    Ok(())
}
 
fn io_bound_threads() -> Result<(), rayon::ThreadPoolBuildError> {
    // I/O-bound: threads > CPU cores (threads wait on I/O)
    let cpu_count = num_cpus::get();
    let io_pool = ThreadPoolBuilder::new()
        .num_threads(cpu_count * 4) // Oversubscription helps I/O
        .build()?;
    
    io_pool.install(|| {
        (0..100)
            .into_par_iter()
            .map(|_| {
                // Simulated I/O wait
                std::thread::sleep(std::time::Duration::from_millis(10));
                1
            })
            .sum::<i32>()
    });
    
    Ok(())
}

CPU-bound work matches thread count to cores; I/O-bound work benefits from oversubscription.

Contention and Thread Count

use rayon::ThreadPoolBuilder;
use std::sync::atomic::{AtomicU32, Ordering};
 
fn contention_example() -> Result<(), rayon::ThreadPoolBuildError> {
    let counter = AtomicU32::new(0);
    
    // More threads = more contention on shared state
    let many_threads = ThreadPoolBuilder::new()
        .num_threads(16)
        .build()?;
    
    many_threads.install(|| {
        (0..1_000_000)
            .into_par_iter()
            .for_each(|_| {
                counter.fetch_add(1, Ordering::Relaxed);
            });
    });
    
    // Fewer threads = less contention
    let few_threads = ThreadPoolBuilder::new()
        .num_threads(2)
        .build()?;
    
    Ok(())
}

High contention scenarios may benefit from fewer threads to reduce synchronization overhead.

Thread Name Configuration

use rayon::ThreadPoolBuilder;
 
fn named_threads() -> Result<(), rayon::ThreadPoolBuildError> {
    let pool = ThreadPoolBuilder::new()
        .num_threads(4)
        .thread_name(|index| format!("worker-{}", index))
        .build()?;
    
    pool.install(|| {
        (0..100)
            .into_par_iter()
            .for_each(|i| {
                // Thread name visible in debugger/profiler
                println!("Processing {} on thread: {:?}", 
                    i, 
                    std::thread::current().name()
                );
            });
    });
    
    Ok(())
}

Named threads help identify worker threads in debugging and profiling tools.

Panic Handling

use rayon::ThreadPoolBuilder;
 
fn panic_handling() -> Result<(), rayon::ThreadPoolBuildError> {
    let pool = ThreadPoolBuilder::new()
        .num_threads(4)
        .panic_handler(|panic_info| {
            eprintln!("Thread panicked: {:?}", panic_info);
        })
        .build()?;
    
    pool.install(|| {
        (0..10)
            .into_par_iter()
            .for_each(|i| {
                if i == 5 {
                    panic!("Unexpected value!");
                }
            });
    });
    
    Ok(())
}

Custom panic handlers allow graceful handling of thread panics.

Comparing Thread Counts

use rayon::ThreadPoolBuilder;
use std::time::Instant;
 
fn benchmark_thread_counts() {
    let cpu_count = num_cpus::get();
    let data: Vec<i32> = (0..10_000_000).collect();
    
    for threads in [1, 2, 4, 8, 16, cpu_count] {
        if threads > cpu_count * 2 {
            continue;
        }
        
        let pool = ThreadPoolBuilder::new()
            .num_threads(threads)
            .build()
            .unwrap();
        
        let start = Instant::now();
        
        pool.install(|| {
            let sum: i64 = data.par_iter()
                .map(|&x| x as i64 * x as i64)
                .sum();
            sum
        });
        
        let elapsed = start.elapsed();
        println!("Threads: {}, Time: {:?}", threads, elapsed);
    }
}

Benchmarking different thread counts reveals optimal parallelism for specific workloads.

Real-World Example: Data Processing Pipeline

use rayon::ThreadPoolBuilder;
 
struct DataProcessor {
    pool: rayon::ThreadPool,
}
 
impl DataProcessor {
    fn new(available_cores: usize) -> Result<Self, rayon::ThreadPoolBuildError> {
        // Use 75% of available cores, leaving room for other work
        let worker_threads = (available_cores * 3 / 4).max(1);
        
        let pool = ThreadPoolBuilder::new()
            .num_threads(worker_threads)
            .thread_name(|i| format!("data-processor-{}", i))
            .build()?;
        
        Ok(Self { pool })
    }
    
    fn process_batch(&self, batch: &[i32]) -> i64 {
        self.pool.install(|| {
            batch.par_iter()
                .map(|&x| self.transform(x))
                .sum()
        })
    }
    
    fn transform(&self, value: i32) -> i64 {
        // CPU-intensive transformation
        (value as i64).pow(2)
    }
}
 
fn main_example() -> Result<(), rayon::ThreadPoolBuildError> {
    let processor = DataProcessor::new(num_cpus::get())?;
    let data: Vec<i32> = (0..1_000_000).collect();
    let result = processor.process_batch(&data);
    println!("Result: {}", result);
    Ok(())
}

Production systems often reserve cores for other processes.

Real-World Example: Web Service Worker Pool

use rayon::ThreadPoolBuilder;
use std::sync::Arc;
 
struct ServicePool {
    cpu_pool: rayon::ThreadPool,
    io_pool: rayon::ThreadPool,
}
 
impl ServicePool {
    fn new() -> Result<Self, rayon::ThreadPoolBuildError> {
        let cores = num_cpus::get();
        
        // CPU-bound work: match core count
        let cpu_pool = ThreadPoolBuilder::new()
            .num_threads(cores)
            .thread_name(|i| format!("cpu-worker-{}", i))
            .build()?;
        
        // I/O-bound work: allow oversubscription
        let io_pool = ThreadPoolBuilder::new()
            .num_threads(cores * 2)
            .thread_name(|i| format!("io-worker-{}", i))
            .build()?;
        
        Ok(Self { cpu_pool, io_pool })
    }
    
    fn process_cpu_intensive(&self, data: &[i32]) -> i64 {
        self.cpu_pool.install(|| {
            data.par_iter()
                .map(|&x| (x as f64).sin().cos().tan() as i64)
                .sum()
        })
    }
    
    fn process_io_intensive<F, T>(&self, tasks: &[F]) -> Vec<T>
    where
        F: Fn() -> T + Sync + Send,
        T: Send,
    {
        self.io_pool.install(|| {
            tasks.par_iter().map(|f| f()).collect()
        })
    }
}

Different pools with different thread counts serve different workload types.

Environment Variable Configuration

use rayon::ThreadPoolBuilder;
 
fn configure_from_env() -> Result<(), rayon::ThreadPoolBuildError> {
    let default_threads = num_cpus::get();
    
    let num_threads = std::env::var("RAYON_NUM_THREADS")
        .ok()
        .and_then(|s| s.parse().ok())
        .unwrap_or(default_threads);
    
    let pool = ThreadPoolBuilder::new()
        .num_threads(num_threads)
        .build_global()?;
    
    Ok(())
}

Configurable thread counts allow tuning without recompilation.

Thread Count Trade-offs

use rayon::ThreadPoolBuilder;
 
fn trade_offs() -> Result<(), rayon::ThreadPoolBuildError> {
    // Too few threads:
    // - Underutilizes CPU cores
    // - Lower throughput
    // - Longer processing time
    
    // Too many threads:
    // - Oversubscription causes context switching
    // - Increased memory usage
    // - Potential contention on shared resources
    // - Diminishing returns
    
    // Just right:
    // - Match CPU cores for CPU-bound work
    // - Allow oversubscription for I/O-bound work
    // - Consider memory constraints
    
    let cpu_count = num_cpus::get();
    
    let optimal_cpu_bound = ThreadPoolBuilder::new()
        .num_threads(cpu_count)
        .build()?;
    
    let optimal_io_bound = ThreadPoolBuilder::new()
        .num_threads(cpu_count * 2)
        .build()?;
    
    let memory_constrained = ThreadPoolBuilder::new()
        .num_threads(2)
        .build()?;
    
    Ok(())
}

Thread count tuning balances parallelism against resource constraints.

Synthesis

Key behaviors:

Thread Count Effect
num_threads(1) Sequential execution (no parallelism)
num_threads(cpu_count) Optimal for CPU-bound work
num_threads(cpu_count * 2) Good for mixed workloads
num_threads(cpu_count * 4) Appropriate for I/O-bound work

Configuration options:

Method Purpose
num_threads(n) Set worker thread count
stack_size(bytes) Set per-thread stack size
thread_name(fn) Name threads for debugging
panic_handler(fn) Handle panics gracefully
build_global() Configure global pool
build() Create custom pool

When to customize:

Scenario Recommended Thread Count
CPU-intensive computation CPU cores
I/O-bound work CPU cores × 2-4
Memory-constrained environment Minimal (2-4)
Multiple services on same machine Subset of cores
Development/testing Smaller count for reproducibility

Key insight: rayon::ThreadPoolBuilder::num_threads provides fine-grained control over parallelism levels, enabling optimization for specific hardware and workload characteristics. The default one-thread-per-core configuration works well for CPU-bound work, but real-world applications often need different thread counts: fewer threads when memory is constrained or when running alongside other services, more threads for I/O-bound work where threads spend time waiting. Multiple thread pools with different thread counts can serve different phases of a workload—CPU-intensive parallel map-reduce operations might use one pool while I/O-heavy network calls use another. The trade-off is between parallelism (more threads) and overhead (context switching, memory, contention). Understanding your workload's CPU vs I/O characteristics, memory constraints, and co-tenant services guides the optimal thread count selection.