let buffer: Arc<Mutex<Vec<u32>>> =
    Arc::new(Mutex::new(vec![0; width * height]));

This would have been fine if I was writing to the buffer once, when the whole rendering finished.

Of course this is not how I set up the ray-tracer. I set it up so that I could observe the raytracing process. I was updating the window with the in-progress buffer, using another buffer to store the sum of all samples, like this:

progress_buffer[index] += render_ray(&ray, &*scene.world, ray_depth);
buffer[index] = color_u32(gamma_correction(
    progress_buffer[index] / (1.0 + sample as f64),
));

When I implemented multi-threading using the Mutex I ran into a starvation issue which was hard to debug - the main thread tried to render at 60 FPS, but if it took slightly longer to update the window, it would monopolize the Mutex, eventually grinding the ray-tracer to a halt.

Unsafe to the rescue

I always knew that the way I set up multi-threading - by giving each worker thread its own piece of the buffer to render, should not require any synchronization. But such shenanigans are not the Rust way. Finally I decided to take the leap.

This is the final demo:

use minifb::{Key, Window, WindowOptions};
use std::thread;

fn main() {
    let (window_width, window_height) = (400, 200);
    let target_fps = 10.0;
    let mut window = Window::new(
        "Raytracer",
        window_width,
        window_height,
        WindowOptions::default(),
    )
    .unwrap();
    let buffer_len = window_width * window_height;
    let mut buffer = vec![color((1.0, 0.7, 0.0)); buffer_len];
    let buffer_ptr = buffer.as_mut_ptr() as usize;

    let num_workers = 8;
    let worker_len = buffer_len / num_workers;

    for ithread in 0..num_workers {
        thread::spawn(move || {
            let thread_ptr = buffer_ptr as *mut u32;
            for i in 0..worker_len {
                thread::sleep(std::time::Duration::from_millis(2));
                unsafe {
                    *thread_ptr.add(ithread * worker_len + i) =
                        color((1.0 / ((1 + ithread) as f64).powf(0.3), 1.0, 0.5));
                }
            }
        });
    }

    window.limit_update_rate(None);
    while window.is_open() && !window.is_key_down(Key::Escape) {
        window
            .update_with_buffer(&buffer, window_width, window_height)
            .unwrap();
        thread::sleep(std::time::Duration::from_secs_f64(1.0 / target_fps))
    }
}

pub fn color((r, g, b): (f64, f64, f64)) -> u32 {
    color_256_u32(r * 255.999, g * 255.999, b * 255.999, 255.0)
}

pub fn color_256_u32(red: f64, green: f64, blue: f64, alpha: f64) -> u32 {
    ((alpha as u32) << 24) + // shift to align
     ((red as u32) << 16) + // shift to align
     ((green as u32) << 8) + // shift to align
     (blue as u32)
}

Let's ignore the minifb boilerplate and focus on the interesting piece.

First of all, Rust doesn't allow passing pointers between threads, as a safety measure. To get around it, we need to cast the pointer to a primitive integer:

let buffer_ptr = buffer.as_mut_ptr() as usize;

It's important to use usize, otherwise we could trim the pointer and end pointing to an entirely different place in memory and SIGSEGV panics.

Once in the worker thread, we can turn the integer back to a pointer:

let thread_ptr = buffer_ptr as *mut u32;

Here instead the u32 determines the type of what we want to store at the pointer location, which for minifb buffers are colors encoded into 32 bits.

Finally, we write to the correct place in the buffer, and voila, we get our real-time progress demo. There is no need to synchronize here because we don't care about the state of each worker thread - even if it was mid-writing a byte, in the worst case it would give us some strange color for a single pixel. In practice, the whole 32bit write looks atomic on my OS.