Arc<Mutex>

Guides

Rust walkthroughs

← Back to all guides

How does rayon::iter::ParallelIterator::inspect differ from map for side effects without transformation?

rayon::iter::ParallelIterator::inspect applies a function to each element for side effects while passing through the original value unchanged, whereas map transforms each element and returns the transformed result—inspect preserves the item type while map changes it. This distinction matters in parallel code where you want to observe or log items without disrupting the pipeline or changing the element type.

Understanding the Type Signatures

use rayon::iter::{IntoParallelIterator, ParallelIterator};
 
fn type_signatures() {
    // inspect signature (conceptually):
    // fn inspect<F>(self, f: F) -> impl ParallelIterator<Item = Self::Item>
    // where F: Fn(&Self::Item) + Sync + Send
    //
    // map signature (conceptually):
    // fn map<F, T>(self, f: F) -> impl ParallelIterator<Item = T>
    // where F: Fn(Self::Item) -> T + Sync + Send
    
    // Key difference:
    // - inspect: takes &T, returns nothing, keeps T
    // - map: takes T, returns U, changes type to U
    
    let data = vec![1, 2, 3, 4, 5];
    
    // inspect preserves the original items
    let result: Vec<i32> = data.par_iter()
        .inspect(|x| println!("Processing: {}", x))
        .copied()
        .collect();
    // Result: [1, 2, 3, 4, 5] - unchanged
    
    // map transforms items
    let result: Vec<i32> = data.par_iter()
        .copied()
        .map(|x| x * 2)
        .collect();
    // Result: [2, 4, 6, 8, 10] - transformed
}

inspect keeps the same item type; map transforms to a new type.

Inspect for Side Effects

use rayon::iter::{IntoParallelIterator, ParallelIterator};
 
fn inspect_side_effects() {
    let data = vec![1, 2, 3, 4, 5];
    
    // inspect allows side effects without changing the pipeline
    let sum: i32 = data.par_iter()
        .inspect(|x| {
            // This side effect runs but doesn't change x
            println!("Before sum, processing: {}", x);
        })
        .sum();
    
    // The sum is correct; items were passed through unchanged
    assert_eq!(sum, 15);
    
    // Pipeline continues with the same type
    let doubled: Vec<i32> = data.par_iter()
        .inspect(|x| println!("About to double: {}", x))
        .map(|x| x * 2)
        .collect();
}

inspect runs side effects but passes items through unchanged.

Map for Transformation

use rayon::iter::{IntoParallelIterator, ParallelIterator};
 
fn map_transformation() {
    let data = vec![1, 2, 3, 4, 5];
    
    // map transforms items to a new type
    let strings: Vec<String> = data.par_iter()
        .map(|x| format!("number_{}", x))
        .collect();
    
    // Type changed from &i32 to String
    assert_eq!(strings, vec!["number_1", "number_2", "number_3", "number_4", "number_5"]);
    
    // map must return a value; the original is consumed
    let doubled: Vec<i32> = data.par_iter()
        .copied()
        .map(|x| x * 2)
        .collect();
    
    // Original values are transformed, not preserved
    assert_eq!(doubled, vec![2, 4, 6, 8, 10]);
}

map transforms values and changes the type; the original item is consumed.

Why Not Use map for Side Effects?

use rayon::iter::{IntoParallelIterator, ParallelIterator};
 
fn why_not_map_for_side_effects() {
    let data = vec![1, 2, 3, 4, 5];
    
    // Using map for side effects is awkward:
    let result: Vec<i32> = data.par_iter()
        .map(|x| {
            println!("Side effect: {}", x);
            *x  // Must return the same value to preserve it
        })
        .collect();
    
    // Problems with using map:
    // 1. Must explicitly return the value
    // 2. Type stays same but looks like transformation
    // 3. Less clear intent (is this transforming or observing?)
    
    // Using inspect is clearer:
    let result: Vec<i32> = data.par_iter()
        .inspect(|x| println!("Side effect: {}", x))
        .copied()
        .collect();
    
    // Benefits:
    // 1. Closure returns () - can't forget to return
    // 2. Intent is clear: observation, not transformation
    // 3. Type is obviously preserved
}

inspect makes the intent clear: observation only, no transformation.

Type Preservation in Chains

use rayon::iter::{IntoParallelIterator, ParallelIterator};
 
fn type_preservation() {
    let data = vec!["apple", "banana", "cherry"];
    
    // inspect preserves type throughout the chain
    let result: Vec<&str> = data.par_iter()
        .inspect(|s| println!("Processing: {}", s))
        .inspect(|s| println!("Length: {}", s.len()))
        .filter(|s| s.len() > 5)
        .inspect(|s| println!("After filter: {}", s))
        .copied()
        .collect();
    
    // All inspect calls preserve the &str type
    // The chain continues with the same type
    
    // map would change types at each step:
    let lengths: Vec<usize> = data.par_iter()
        .map(|s| s.len())  // Type changes to usize
        .collect();
}

Multiple inspect calls chain naturally with the same type throughout.

Debugging Parallel Pipelines

use rayon::iter::{IntoParallelIterator, ParallelIterator};
 
fn debugging_pipelines() {
    let data = vec![1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
    
    // inspect is invaluable for debugging parallel pipelines
    let result: Vec<i32> = data.par_iter()
        .inspect(|x| println!("Input: {}", x))
        .copied()
        .filter(|x| x % 2 == 0)
        .inspect(|x| println!("After filter: {}", x))
        .map(|x| x * 3)
        .inspect(|x| println!("After map: {}", x))
        .collect();
    
    // Each inspect shows the state at that point
    // Without disrupting the pipeline or changing types
    
    // Compare to using map for debugging:
    let result: Vec<i32> = data.par_iter()
        .copied()
        .filter(|x| x % 2 == 0)
        .map(|x| {
            println!("After filter: {}", x);
            x  // Must remember to return x
        })
        .map(|x| {
            let result = x * 3;
            println!("After map: {}", result);
            result
        })
        .collect();
}

inspect is ideal for debugging parallel pipelines without altering them.

Immutable Access with inspect

use rayon::iter::{IntoParallelIterator, ParallelIterator};
 
fn immutable_access() {
    let data = vec![User { id: 1, name: "Alice".to_string() },
                    User { id: 2, name: "Bob".to_string() }];
    
    // inspect provides immutable reference
    data.par_iter()
        .inspect(|user| {
            // Can read but not modify
            println!("User {}: {}", user.id, user.name);
        })
        .for_each(|user| {
            // Process user
        });
    
    // map takes ownership or requires copying
    data.par_iter()
        .map(|user| {
            println!("User {}: {}", user.id, user.name);
            user.id  // Must decide what to return
        })
        .collect::<Vec<_>>();
}
 
#[derive(Debug, Clone)]
struct User {
    id: i32,
    name: String,
}

inspect provides immutable references, preserving the original items.

Performance Considerations

use rayon::iter::{IntoParallelIterator, ParallelIterator};
 
fn performance_notes() {
    // ┌─────────────────────────────────────────────────────────────────────────┐
    // │ Aspect        │ inspect                  │ map                        │
    // ├─────────────────────────────────────────────────────────────────────────┤
    // │ Closure arg   │ &T (borrow)              │ T (owned or moved)         │
    // │ Return value  │ () - discarded           │ U - collected              │
    // │ Type change   │ None - keeps T          │ Yes - becomes U            │
    // │ Overhead      │ Function call only      │ Function call + new value  │
    // │ Use case      │ Side effects, logging    │ Transformation              │
    // └─────────────────────────────────────────────────────────────────────────┘
    
    // inspect has slightly less overhead when you don't need transformation:
    // - No need to construct a return value
    // - No type transformation
    // - Just the function call for side effects
    
    let data: Vec<i32> = (0..1000).collect();
    
    // For pure side effects, inspect is clearer:
    data.par_iter()
        .inspect(|x| { /* side effect */ })
        .for_each(|_| {});
    
    // map would require returning something:
    data.par_iter()
        .map(|x| { /* side effect */; x })  // Must return value
        .for_each(|_| {});
}

inspect has minimal overhead since it doesn't transform values.

Counting or Metrics with inspect

use rayon::iter::{IntoParallelIterator, ParallelIterator};
use std::sync::atomic::{AtomicUsize, Ordering};
 
fn metrics_with_inspect() {
    let data = vec![1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
    let processed_count = AtomicUsize::new(0);
    
    // Use inspect for metrics without disrupting pipeline
    let result: Vec<i32> = data.par_iter()
        .inspect(|_| {
            processed_count.fetch_add(1, Ordering::Relaxed);
        })
        .copied()
        .filter(|x| x % 2 == 0)
        .collect();
    
    println!("Processed {} items", processed_count.load(Ordering::Relaxed));
    
    // The pipeline result is unaffected by the metrics
    assert_eq!(result, vec![2, 4, 6, 8, 10]);
}

inspect is useful for collecting metrics without changing the pipeline.

Conditional Side Effects

use rayon::iter::{IntoParallelIterator, ParallelIterator};
 
fn conditional_side_effects() {
    let data = vec![1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
    
    // inspect for conditional logging
    let result: Vec<i32> = data.par_iter()
        .inspect(|x| {
            if **x > 5 {
                println!("Large value: {}", x);
            }
        })
        .copied()
        .map(|x| x * 2)
        .collect();
    
    // Side effects only for items matching condition
    // Pipeline continues unchanged
    
    // Compare with map for conditional logging:
    let result: Vec<i32> = data.par_iter()
        .copied()
        .map(|x| {
            if x > 5 {
                println!("Large value: {}", x);
            }
            x * 2  // Must return the transformed value
        })
        .collect();
}

inspect allows conditional side effects without affecting the transformation.

Combining inspect and map

use rayon::iter::{IntoParallelIterator, ParallelIterator};
 
fn combining_inspect_and_map() {
    let data = vec!["1", "2", "3", "4", "5"];
    
    // Common pattern: inspect before/after transformation
    let result: Vec<i32> = data.par_iter()
        .inspect(|s| println!("Parsing: {}", s))
        .map(|s| s.parse::<i32>().unwrap())
        .inspect(|n| println!("Parsed: {}", n))
        .map(|n| n * 2)
        .inspect(|n| println!("Doubled: {}", n))
        .collect();
    
    // This pattern shows the data at each transformation step
    // Without inspect, you'd need multiple map calls with debug output
    // and careful return value handling
}

Combine inspect and map for clear pipelines with observation points.

Error Handling Differences

use rayon::iter::{IntoParallelIterator, ParallelIterator};
 
fn error_handling() {
    let data = vec!["1", "2", "three", "4", "5"];
    
    // inspect can't affect error handling - it's for observation
    // Errors must be handled elsewhere in the pipeline
    
    data.par_iter()
        .inspect(|s| println!("Attempting to parse: {}", s))
        .map(|s| s.parse::<i32>())
        .filter_map(|r| r.ok())  // Handle errors after inspect
        .collect::<Vec<_>>();
    
    // map can handle errors inline:
    data.par_iter()
        .map(|s| {
            s.parse::<i32>()
                .map_err(|e| println!("Error parsing '{}': {}", s, e))
                .ok()
        })
        .flatten()
        .collect::<Vec<_>>();
}

inspect is purely observation; error handling must happen elsewhere.

Complete Summary

use rayon::iter::{IntoParallelIterator, ParallelIterator};
 
fn complete_summary() {
    // ┌─────────────────────────────────────────────────────────────────────────┐
    // │ Characteristic       │ inspect                │ map                    │
    // ├─────────────────────────────────────────────────────────────────────────┤
    // │ Purpose              │ Observation/side effects│ Transformation        │
    // │ Closure parameter    │ &T (immutable borrow)  │ T (ownership)          │
    // │ Closure return       │ () - discarded         │ U - new type           │
    // │ Output type          │ Same as input (T)      │ Changed (U)            │
    // │ Original value       │ Preserved              │ Consumed/replaced      │
    // │ Common use           │ Logging, metrics       │ Data transformation    │
    // │ Chaining             │ Same type throughout   │ Types can change       │
    // │ Intent signal        │ "Observing only"       │ "Transforming"         │
    // └─────────────────────────────────────────────────────────────────────────┘
    
    let data = vec![1, 2, 3, 4, 5];
    
    // inspect: observe without changing
    let result: Vec<i32> = data.par_iter()
        .inspect(|x| println!("Processing {}", x))  // Side effect
        .copied()
        .collect();
    // result == [1, 2, 3, 4, 5]
    
    // map: transform values
    let result: Vec<i32> = data.par_iter()
        .copied()
        .map(|x| x * 2)  // Transformation
        .collect();
    // result == [2, 4, 6, 8, 10]
    
    // Key insight:
    // Use inspect when you want to see values without changing them.
    // Use map when you want to transform values into new values.
    // Using map for side effects is possible but less clear:
    // - Must return a value (often the same one)
    // - Intent is ambiguous (transforming or observing?)
    // - Type changes may complicate the pipeline
}
 
// Key insight:
// `inspect` and `map` serve fundamentally different purposes.
// `inspect` is for observation - running side effects while
// passing values through unchanged. `map` is for transformation
// - consuming values and producing new ones. In parallel code,
// `inspect` is particularly useful because:
//
// 1. It clearly signals "this is for observation"
// 2. It preserves the pipeline type without ceremony
// 3. It works at any point in the chain without type adjustments
// 4. It provides immutable access to items
//
// Use `inspect` for logging, metrics, debugging, and any side
// effects that don't need to transform the data. Use `map` when
// you actually need to change the values or their type.

Key insight: inspect provides observation without transformation—it takes an immutable reference, returns (), and preserves the original item type. map provides transformation—it takes ownership, returns a new value, and changes the type. Using map for side effects requires awkward constructs like returning the original value and obscures intent. inspect makes observation explicit and preserves pipeline types naturally, making it ideal for logging, debugging, metrics, and any side effects in parallel code where you want to observe without disrupting the data flow.