GPU Wait API Migration: Boolean to Result Implementation

Fixes #248 | Inspired by zed-industries/zed#43070

Problem

The wait_for API provides GPU synchronization by blocking until the GPU reaches a specific sync point, preventing the CPU from destroying or reusing resources while they're still in use. When you submit work to the GPU (like rendering a frame), it continues running asynchronously. Without proper synchronization, the CPU could delete textures or reuse buffers while the GPU is still accessing them, causing memory corruption or crashes.

Current limitation: Returns a simple boolean that loses critical error information:

• ❌ Timeouts look the same as device loss
• ❌ Backend-specific failures indistinguishable
• ❌ All failures return false - no context for recovery
• ❌ Callers can't make informed decisions about resource cleanup

Solution

Introduce Result-based error handling while maintaining backward compatibility.

Migration Strategy

Dual implementation approach:

• ✅ Existing wait_for() → bool (preserved, delegates to new method)
• ✨ New wait_for_result() → Result<(), WaitError> (detailed errors)

New Error Type

pub enum WaitError {
    Timeout,        // Operation timed out, GPU still busy
    DeviceLost,     // GPU device lost/removed (unrecoverable)
    OutOfDate,      // Resource out of date (Vulkan swapchain)
    Other(String),  // Backend-specific errors with details
}

New Trait Method

fn wait_for_result(&self, sp: &Self::SyncPoint, timeout_ms: u32) 
    -> Result<(), WaitError>;

Backend Implementations

Each backend maps its native error conditions to WaitError:

Usage Patterns

Frame Synchronization (Frame Pacer)

Before: Blind wait, no error handling

context.wait_for(&sp, !0);
// Always cleanup, even if device lost

After: Conditional cleanup based on error

match context.wait_for_result(&sp, !0) {
    Ok(()) => { /* cleanup resources */ }
    Err(WaitError::DeviceLost) => { 
        cleanup = false; // Prevent crashes on device loss
    }
    Err(e) => { cleanup = false; }
}

Buffer Reuse (Buffer Belt)

Before: Can't distinguish busy from error

// false could mean "busy" or "device lost"
if gpu.wait_for(sp, 0) { reuse_buffer() }

After: Intelligent reuse decisions

match gpu.wait_for_result(sp, 0) {
    Ok(()) => true,                    // Safe to reuse
    Err(WaitError::Timeout) => false,  // Still busy, try later
    Err(e) => {                        // Unexpected error
        log::warn!("Unexpected: {:?}", e);
        false
    }
}

Texture Cleanup (EGUI)

After: Partition textures by readiness state

• Ok(()) → Delete immediately
• Timeout → Keep for next frame
• Other errors → Keep with warning

Shader Hot Reload

After: Block critical operations on device loss

match gpu.wait_for_result(sync_point, !0) {
    Ok(()) => { /* safe to reload shaders */ }
    Err(WaitError::DeviceLost) => {
        log::error!("Cannot reload: device lost");
        return false; // Prevent crash
    }
    Err(e) => { /* log, continue with caution */ }
}

Benefits

✅ Actionable Error Information: Distinguish timeouts (retry later) from device loss (unrecoverable)
✅ Safer Resource Management: Skip cleanup on device loss to prevent crashes
✅ Better Debugging: Detailed error messages from backend-specific failures
✅ Backward Compatible: Existing wait_for callers continue working unchanged
✅ Foundation for Recovery: Enables future device loss recovery strategies

Migration Path

1. ✅ Add WaitError enum and wait_for_result to trait
2. ✅ Implement in all backends (Vulkan, GLES, Metal)
3. ✅ Make wait_for delegate to wait_for_result
4. ✅ Migrate critical usage sites (frame pacer, buffer belt, texture cleanup, shader reload)
5. 🔜 Future: Deprecate boolean API, full migration to Result-based API