Skip to main content

oxigeo_gpu/
multi_gpu.rs

1//! Multi-GPU support for distributed GPU computing.
2//!
3//! This module provides infrastructure for managing multiple GPUs,
4//! distributing work across devices, and handling inter-GPU data transfers.
5
6use crate::context::{GpuContext, GpuContextConfig};
7use crate::error::{GpuError, GpuResult};
8use std::collections::HashMap;
9use std::sync::atomic::{AtomicUsize, Ordering};
10use std::sync::{Arc, Mutex};
11use tracing::{debug, info, warn};
12use wgpu::{Adapter, AdapterInfo, Backend, Backends, BufferUsages, Instance, PollType};
13
14/// Multi-GPU configuration.
15#[derive(Debug, Clone)]
16pub struct MultiGpuConfig {
17    /// Backends to search for GPUs.
18    pub backends: Backends,
19    /// Minimum number of GPUs required.
20    pub min_devices: usize,
21    /// Maximum number of GPUs to use.
22    pub max_devices: usize,
23    /// Enable automatic load balancing.
24    pub auto_load_balance: bool,
25    /// Enable peer-to-peer transfers (if supported).
26    pub enable_p2p: bool,
27}
28
29impl Default for MultiGpuConfig {
30    fn default() -> Self {
31        Self {
32            backends: Backends::all(),
33            min_devices: 1,
34            max_devices: 8,
35            auto_load_balance: true,
36            enable_p2p: false,
37        }
38    }
39}
40
41/// Information about a GPU device.
42#[derive(Debug, Clone)]
43pub struct GpuDeviceInfo {
44    /// Device index.
45    pub index: usize,
46    /// Adapter information.
47    pub adapter_info: AdapterInfo,
48    /// Backend type.
49    pub backend: Backend,
50    /// Coarse VRAM estimate in bytes, derived from the adapter's device type
51    /// bucket (discrete/integrated/virtual) — **not** a measured figure.
52    ///
53    /// wgpu does not expose real adapter memory portably, so this is a rough
54    /// per-category heuristic (`MultiGpuManager::estimate_vram_coarse`).  Do
55    /// not treat it as the true VRAM of a specific card: two different discrete
56    /// GPUs will report the same value.  Callers making VRAM-budget decisions
57    /// (e.g. tile sizing) should treat this as a conservative lower-bound hint,
58    /// not ground truth.
59    pub vram_bytes: Option<u64>,
60    /// Device is currently active.
61    pub active: bool,
62}
63
64impl GpuDeviceInfo {
65    /// Get a human-readable description.
66    pub fn description(&self) -> String {
67        format!(
68            "GPU {} : {} ({:?})",
69            self.index, self.adapter_info.name, self.backend
70        )
71    }
72}
73
74/// Multi-GPU manager for coordinating multiple devices.
75pub struct MultiGpuManager {
76    /// Available GPU contexts.
77    devices: Vec<Arc<GpuContext>>,
78    /// Device information.
79    device_info: Vec<GpuDeviceInfo>,
80    /// Configuration.
81    config: MultiGpuConfig,
82    /// Load balancing state.
83    load_state: Arc<Mutex<LoadBalanceState>>,
84    /// Monotonic counter used for round-robin device selection when load
85    /// balancing is disabled.  Incremented on every `select_device()` call.
86    round_robin: AtomicUsize,
87}
88
89impl MultiGpuManager {
90    /// Create a zero-device manager without touching any wgpu objects.
91    ///
92    /// Used exclusively in tests to construct `InterGpuTransfer` instances
93    /// that exercise the pure-Rust validation paths in `gather` without
94    /// requiring a physical GPU or wgpu backend initialization.
95    #[cfg(test)]
96    pub(crate) fn new_empty_for_testing() -> Self {
97        Self {
98            devices: Vec::new(),
99            device_info: Vec::new(),
100            config: MultiGpuConfig::default(),
101            load_state: Arc::new(Mutex::new(LoadBalanceState::new(0))),
102            round_robin: AtomicUsize::new(0),
103        }
104    }
105}
106
107#[derive(Debug, Clone)]
108struct LoadBalanceState {
109    /// Number of tasks dispatched to each device.
110    task_counts: HashMap<usize, usize>,
111    /// Estimated workload on each device (arbitrary units).
112    workload: HashMap<usize, f64>,
113}
114
115impl LoadBalanceState {
116    fn new(num_devices: usize) -> Self {
117        let mut task_counts = HashMap::new();
118        let mut workload = HashMap::new();
119
120        for i in 0..num_devices {
121            task_counts.insert(i, 0);
122            workload.insert(i, 0.0);
123        }
124
125        Self {
126            task_counts,
127            workload,
128        }
129    }
130
131    fn select_device(&self) -> usize {
132        // Select device with minimum workload
133        self.workload
134            .iter()
135            .min_by(|a, b| a.1.partial_cmp(b.1).unwrap_or(std::cmp::Ordering::Equal))
136            .map(|(idx, _)| *idx)
137            .unwrap_or(0)
138    }
139
140    fn add_task(&mut self, device: usize, workload: f64) {
141        *self.task_counts.entry(device).or_insert(0) += 1;
142        *self.workload.entry(device).or_insert(0.0) += workload;
143    }
144
145    fn complete_task(&mut self, device: usize, workload: f64) {
146        if let Some(count) = self.task_counts.get_mut(&device) {
147            *count = count.saturating_sub(1);
148        }
149        if let Some(load) = self.workload.get_mut(&device) {
150            *load = load.max(workload) - workload;
151        }
152    }
153}
154
155impl MultiGpuManager {
156    /// Create a new multi-GPU manager.
157    ///
158    /// # Errors
159    ///
160    /// Returns an error if minimum number of devices cannot be found.
161    pub async fn new(config: MultiGpuConfig) -> GpuResult<Self> {
162        info!("Initializing multi-GPU manager");
163
164        let instance = Instance::new(wgpu::InstanceDescriptor {
165            backends: config.backends,
166            ..wgpu::InstanceDescriptor::new_without_display_handle()
167        });
168
169        // Enumerate all available adapters
170        let adapters = Self::enumerate_adapters(&instance).await;
171
172        if adapters.len() < config.min_devices {
173            return Err(GpuError::no_adapter(format!(
174                "Found {} GPUs, but {} required",
175                adapters.len(),
176                config.min_devices
177            )));
178        }
179
180        let num_devices = adapters.len().min(config.max_devices);
181        info!(
182            "Found {} compatible GPUs, using {}",
183            adapters.len(),
184            num_devices
185        );
186
187        // Create contexts for each device
188        let mut devices = Vec::new();
189        let mut device_info = Vec::new();
190
191        for (index, adapter) in adapters.into_iter().take(num_devices).enumerate() {
192            match Self::create_device_context(adapter, index).await {
193                Ok((context, info)) => {
194                    devices.push(Arc::new(context));
195                    device_info.push(info);
196                    info!(
197                        "Initialized: {}",
198                        device_info
199                            .last()
200                            .map(|i| i.description())
201                            .unwrap_or_default()
202                    );
203                }
204                Err(e) => {
205                    warn!("Failed to initialize GPU {}: {}", index, e);
206                }
207            }
208        }
209
210        if devices.len() < config.min_devices {
211            return Err(GpuError::device_request(format!(
212                "Successfully initialized {} GPUs, but {} required",
213                devices.len(),
214                config.min_devices
215            )));
216        }
217
218        let load_state = Arc::new(Mutex::new(LoadBalanceState::new(devices.len())));
219
220        Ok(Self {
221            devices,
222            device_info,
223            config,
224            load_state,
225            round_robin: AtomicUsize::new(0),
226        })
227    }
228
229    /// Get the number of available devices.
230    pub fn num_devices(&self) -> usize {
231        self.devices.len()
232    }
233
234    /// Get a specific device context.
235    pub fn device(&self, index: usize) -> Option<&Arc<GpuContext>> {
236        self.devices.get(index)
237    }
238
239    /// Get all device contexts.
240    pub fn devices(&self) -> &[Arc<GpuContext>] {
241        &self.devices
242    }
243
244    /// Get device information.
245    pub fn device_info(&self, index: usize) -> Option<&GpuDeviceInfo> {
246        self.device_info.get(index)
247    }
248
249    /// Get all device information.
250    pub fn all_device_info(&self) -> &[GpuDeviceInfo] {
251        &self.device_info
252    }
253
254    /// Select a device based on load balancing strategy.
255    ///
256    /// When `auto_load_balance` is enabled, the device with the minimum
257    /// estimated workload is chosen.  When it is disabled, a true round-robin
258    /// rotation across all enumerated devices is used (driven by an atomic
259    /// counter) so that every GPU receives work rather than always dispatching
260    /// to device 0.
261    pub fn select_device(&self) -> usize {
262        let num_devices = self.devices.len();
263        if num_devices == 0 {
264            return 0;
265        }
266
267        if !self.config.auto_load_balance {
268            // Round-robin without load balancing: advance the shared atomic
269            // counter and wrap by the device count.
270            return self.next_round_robin(num_devices);
271        }
272
273        self.load_state
274            .lock()
275            .map(|state| state.select_device())
276            .unwrap_or(0)
277    }
278
279    /// Advance the round-robin counter and return the next device index in
280    /// `0..num_devices`.  Factored out so the rotation logic can be unit
281    /// tested without a physical GPU.
282    fn next_round_robin(&self, num_devices: usize) -> usize {
283        if num_devices == 0 {
284            return 0;
285        }
286        self.round_robin.fetch_add(1, Ordering::Relaxed) % num_devices
287    }
288
289    /// Dispatch work to a device with load balancing.
290    pub fn dispatch<F, T>(&self, workload: f64, f: F) -> GpuResult<T>
291    where
292        F: FnOnce(&GpuContext) -> GpuResult<T>,
293    {
294        let device_idx = self.select_device();
295
296        if let Ok(mut state) = self.load_state.lock() {
297            state.add_task(device_idx, workload);
298        }
299
300        let context = self
301            .devices
302            .get(device_idx)
303            .ok_or_else(|| GpuError::internal("Invalid device index"))?;
304
305        let result = f(context);
306
307        if let Ok(mut state) = self.load_state.lock() {
308            state.complete_task(device_idx, workload);
309        }
310
311        result
312    }
313
314    /// Distribute work across all devices.
315    pub async fn distribute<F, T>(&self, items: Vec<(f64, F)>) -> Vec<GpuResult<T>>
316    where
317        F: FnOnce(&GpuContext) -> GpuResult<T> + Send + 'static,
318        T: Send + 'static,
319    {
320        let mut tasks = Vec::new();
321
322        for (workload, work_fn) in items {
323            let device_idx = self.select_device();
324
325            if let Ok(mut state) = self.load_state.lock() {
326                state.add_task(device_idx, workload);
327            }
328
329            let context = match self.devices.get(device_idx) {
330                Some(ctx) => Arc::clone(ctx),
331                None => continue,
332            };
333
334            let load_state = Arc::clone(&self.load_state);
335
336            let task = tokio::spawn(async move {
337                let result = work_fn(&context);
338
339                if let Ok(mut state) = load_state.lock() {
340                    state.complete_task(device_idx, workload);
341                }
342
343                result
344            });
345
346            tasks.push(task);
347        }
348
349        // Wait for all tasks to complete
350        let mut results = Vec::new();
351        for task in tasks {
352            match task.await {
353                Ok(result) => results.push(result),
354                Err(e) => results.push(Err(GpuError::internal(e.to_string()))),
355            }
356        }
357
358        results
359    }
360
361    /// Get current load statistics.
362    pub fn load_stats(&self) -> HashMap<usize, (usize, f64)> {
363        self.load_state
364            .lock()
365            .map(|state| {
366                let mut stats = HashMap::new();
367                for i in 0..self.devices.len() {
368                    let tasks = *state.task_counts.get(&i).unwrap_or(&0);
369                    let workload = *state.workload.get(&i).unwrap_or(&0.0);
370                    stats.insert(i, (tasks, workload));
371                }
372                stats
373            })
374            .unwrap_or_default()
375    }
376
377    async fn enumerate_adapters(_instance: &Instance) -> Vec<Adapter> {
378        let mut adapters = Vec::new();
379
380        // Try each backend
381        for backend in &[
382            Backends::VULKAN,
383            Backends::METAL,
384            Backends::DX12,
385            Backends::BROWSER_WEBGPU,
386        ] {
387            let backend_instance = Instance::new(wgpu::InstanceDescriptor {
388                backends: *backend,
389                ..wgpu::InstanceDescriptor::new_without_display_handle()
390            });
391
392            if let Ok(adapter) = backend_instance
393                .request_adapter(&wgpu::RequestAdapterOptions {
394                    power_preference: wgpu::PowerPreference::HighPerformance,
395                    force_fallback_adapter: false,
396                    compatible_surface: None,
397                    apply_limit_buckets: false,
398                })
399                .await
400            {
401                adapters.push(adapter);
402            }
403        }
404
405        adapters
406    }
407
408    async fn create_device_context(
409        adapter: Adapter,
410        index: usize,
411    ) -> GpuResult<(GpuContext, GpuDeviceInfo)> {
412        let adapter_info = adapter.get_info();
413        let backend = adapter_info.backend;
414
415        // Coarse VRAM estimate (real per-adapter memory is not portably
416        // exposed by wgpu; this is a device-type bucket heuristic).
417        let vram_bytes = Self::estimate_vram_coarse(&adapter_info);
418
419        let config = GpuContextConfig::default().with_label(format!("GPU {}", index));
420
421        let context = GpuContext::with_config(config).await?;
422
423        let info = GpuDeviceInfo {
424            index,
425            adapter_info,
426            backend,
427            vram_bytes,
428            active: true,
429        };
430
431        Ok((context, info))
432    }
433
434    /// Coarse VRAM estimate based purely on the adapter device-type bucket.
435    ///
436    /// This is **not** a measurement: wgpu does not portably expose per-adapter
437    /// dedicated memory, so every discrete GPU maps to the same figure. It
438    /// serves only as a conservative fallback hint for VRAM-budget code. When a
439    /// backend-specific memory query becomes available it should supersede this.
440    fn estimate_vram_coarse(adapter_info: &AdapterInfo) -> Option<u64> {
441        // This is a rough estimation based on device type
442        match adapter_info.device_type {
443            wgpu::DeviceType::DiscreteGpu => Some(8 * 1024 * 1024 * 1024), // 8 GB
444            wgpu::DeviceType::IntegratedGpu => Some(2 * 1024 * 1024 * 1024), // 2 GB
445            wgpu::DeviceType::VirtualGpu => Some(4 * 1024 * 1024 * 1024),  // 4 GB
446            _ => None,
447        }
448    }
449}
450
451/// Inter-GPU data transfer manager.
452///
453/// Maintains a per-device "last submitted buffer" slot so that `gather`
454/// can perform real GPU→CPU readback.  After dispatching work to device `i`,
455/// call [`set_device_buffer`](Self::set_device_buffer) with the result buffer
456/// and its byte-size; then `gather` will DMA-read every registered buffer
457/// back to the host and return the raw bytes.
458pub struct InterGpuTransfer {
459    manager: Arc<MultiGpuManager>,
460    /// Per-device slot: the most-recently registered GPU buffer and its
461    /// byte size, protected by a Mutex so the struct stays `Send + Sync`.
462    per_device_buffers: Vec<Arc<Mutex<Option<(Arc<wgpu::Buffer>, u64)>>>>,
463}
464
465impl InterGpuTransfer {
466    /// Create a new inter-GPU transfer manager.
467    pub fn new(manager: Arc<MultiGpuManager>) -> Self {
468        let num_devices = manager.num_devices();
469        let per_device_buffers = (0..num_devices)
470            .map(|_| Arc::new(Mutex::new(None)))
471            .collect();
472        Self {
473            manager,
474            per_device_buffers,
475        }
476    }
477
478    /// Register the GPU buffer produced by a compute pass on `device_idx`.
479    ///
480    /// The buffer must have at least `BufferUsages::COPY_SRC` so that
481    /// `gather` can issue a copy-to-staging command.
482    ///
483    /// # Errors
484    ///
485    /// Returns [`GpuError::InvalidBuffer`] when `device_idx` is out of range
486    /// or the internal lock is poisoned.
487    pub fn set_device_buffer(
488        &self,
489        device_idx: usize,
490        buffer: Arc<wgpu::Buffer>,
491        size_bytes: u64,
492    ) -> GpuResult<()> {
493        let slot = self
494            .per_device_buffers
495            .get(device_idx)
496            .ok_or_else(|| GpuError::invalid_buffer("device_idx out of range"))?;
497        *slot
498            .lock()
499            .map_err(|_| GpuError::internal("per_device_buffers lock poisoned"))? =
500            Some((buffer, size_bytes));
501        Ok(())
502    }
503
504    /// Copy data between GPUs via the host (staging).
505    ///
506    /// # Errors
507    ///
508    /// Returns an error if transfer fails or devices are invalid.
509    pub async fn copy_buffer(
510        &self,
511        src_device: usize,
512        dst_device: usize,
513        data: &[u8],
514    ) -> GpuResult<()> {
515        let _src_ctx = self
516            .manager
517            .device(src_device)
518            .ok_or_else(|| GpuError::invalid_buffer("Invalid source device"))?;
519
520        let dst_ctx = self
521            .manager
522            .device(dst_device)
523            .ok_or_else(|| GpuError::invalid_buffer("Invalid destination device"))?;
524
525        // Create buffer on destination device
526        let dst_buffer = dst_ctx.device().create_buffer(&wgpu::BufferDescriptor {
527            label: Some("Inter-GPU Transfer"),
528            size: data.len() as u64,
529            usage: BufferUsages::COPY_DST | BufferUsages::STORAGE,
530            mapped_at_creation: false,
531        });
532
533        // Write data to destination
534        dst_ctx.queue().write_buffer(&dst_buffer, 0, data);
535
536        debug!(
537            "Transferred {} bytes from GPU {} to GPU {}",
538            data.len(),
539            src_device,
540            dst_device
541        );
542
543        Ok(())
544    }
545
546    /// Broadcast data to all GPUs.
547    ///
548    /// # Errors
549    ///
550    /// Returns an error if any transfer fails.
551    pub async fn broadcast(&self, data: &[u8]) -> GpuResult<()> {
552        for i in 1..self.manager.num_devices() {
553            self.copy_buffer(0, i, data).await?;
554        }
555
556        Ok(())
557    }
558
559    /// Gather data from every source device to `dst_device`.
560    ///
561    /// For each source device `i` (where `i != dst_device`) that has had a
562    /// buffer registered via [`set_device_buffer`](Self::set_device_buffer),
563    /// this method performs a real GPU→CPU readback:
564    ///
565    /// 1. Allocates a CPU-visible *staging* buffer on device `i`.
566    /// 2. Encodes a `copy_buffer_to_buffer` command from the registered source
567    ///    buffer into the staging buffer, then submits it to the device queue.
568    /// 3. Polls the device until the submission has completed (blocking wait).
569    /// 4. Maps the staging buffer for reading, copies the data, and unmaps it.
570    ///
571    /// The returned `Vec<Vec<u8>>` contains one entry per source device
572    /// (ordered by ascending device index, skipping `dst_device`).  Devices
573    /// that have no registered buffer produce an empty `Vec<u8>`.
574    ///
575    /// # Errors
576    ///
577    /// Returns an error when:
578    /// - `dst_device >= num_devices`
579    /// - the wgpu device poll fails
580    /// - the staging buffer cannot be mapped (e.g., the source buffer is missing
581    ///   `COPY_SRC` usage)
582    /// - an internal mutex is poisoned
583    pub async fn gather(&self, dst_device: usize) -> GpuResult<Vec<Vec<u8>>> {
584        // Use `per_device_buffers.len()` as the authoritative device count.
585        // This equals `manager.num_devices()` at construction time and lets
586        // CPU-only tests construct `InterGpuTransfer` with an empty-device
587        // manager while still exercising the validation and readback paths.
588        let num_devices = self.per_device_buffers.len();
589
590        if dst_device >= num_devices {
591            return Err(GpuError::invalid_buffer(format!(
592                "dst_device {} is out of range (num_devices = {})",
593                dst_device, num_devices
594            )));
595        }
596
597        let mut results: Vec<Vec<u8>> = Vec::with_capacity(num_devices.saturating_sub(1));
598
599        for src_idx in 0..num_devices {
600            if src_idx == dst_device {
601                continue;
602            }
603
604            // Retrieve the registered buffer slot for this device.
605            // We do this before consulting the manager so that the `None`
606            // (no-buffer) fast path never needs a real GpuContext.
607            let slot = self
608                .per_device_buffers
609                .get(src_idx)
610                .ok_or_else(|| GpuError::internal("per_device_buffers shorter than num_devices"))?;
611
612            // Extract the buffer handle inside a nested scope so the
613            // `MutexGuard` is dropped before any `.await` point, satisfying
614            // the `clippy::await_holding_lock` lint.
615            let maybe_buffer_info: Option<(Arc<wgpu::Buffer>, u64)> = {
616                let guard = slot
617                    .lock()
618                    .map_err(|_| GpuError::internal("per_device_buffers lock poisoned"))?;
619                guard.as_ref().map(|(buf, sz)| (Arc::clone(buf), *sz))
620                // `guard` drops here — mutex released before any await.
621            };
622
623            // If no buffer has been registered yet, return empty bytes for this device.
624            let (src_buffer, size_bytes) = match maybe_buffer_info {
625                Some(pair) => pair,
626                None => {
627                    debug!(
628                        "gather: device {} has no registered buffer, returning empty slice",
629                        src_idx
630                    );
631                    results.push(Vec::new());
632                    continue;
633                }
634            };
635
636            // Retrieve the GPU context now that we know we have a buffer to
637            // read.  This call is intentionally placed after the `None` check
638            // so that CPU-only tests (where `manager.device()` would return
639            // `None` for every index) never reach this path.
640            let ctx = self
641                .manager
642                .device(src_idx)
643                .ok_or_else(|| GpuError::invalid_buffer("source device context missing"))?;
644
645            // Step 1 – allocate a MAP_READ | COPY_DST staging buffer on device src_idx.
646            // GPU device objects are not directly accessible from GpuContext because the
647            // Arc<Device> is behind a private field, but `GpuContext::device()` returns a
648            // shared reference `&Device`, which is sufficient for buffer creation and polling.
649            let wgpu_device = ctx.device();
650            let wgpu_queue = ctx.queue();
651
652            let staging = wgpu_device.create_buffer(&wgpu::BufferDescriptor {
653                label: Some("gather_staging"),
654                size: size_bytes,
655                usage: BufferUsages::MAP_READ | BufferUsages::COPY_DST,
656                mapped_at_creation: false,
657            });
658
659            // Step 2 – encode copy_buffer_to_buffer and submit.
660            let mut encoder = wgpu_device.create_command_encoder(&wgpu::CommandEncoderDescriptor {
661                label: Some("gather_copy_encoder"),
662            });
663            encoder.copy_buffer_to_buffer(&src_buffer, 0, &staging, 0, size_bytes);
664            ctx.check_device_lost()?;
665            wgpu_queue.submit(std::iter::once(encoder.finish()));
666
667            // Step 3 – poll the device until the copy submission completes.
668            // wgpu 29 uses `PollType::wait_indefinitely()` which blocks until
669            // all submitted work has finished.
670            wgpu_device
671                .poll(PollType::wait_indefinitely())
672                .map_err(|e| GpuError::execution_failed(format!("device poll error: {e:?}")))?;
673
674            // Step 4 – map the staging buffer and read the raw bytes.
675            let (tx, rx) =
676                futures::channel::oneshot::channel::<Result<(), wgpu::BufferAsyncError>>();
677            staging.slice(..).map_async(wgpu::MapMode::Read, move |r| {
678                let _ = tx.send(r);
679            });
680
681            // Poll once more to drive the mapping callback.
682            wgpu_device
683                .poll(PollType::wait_indefinitely())
684                .map_err(|e| {
685                    GpuError::execution_failed(format!("device poll (map) error: {e:?}"))
686                })?;
687
688            rx.await
689                .map_err(|_| GpuError::buffer_mapping("gather: oneshot channel closed"))?
690                .map_err(|e| GpuError::buffer_mapping(format!("gather: map_async failed: {e}")))?;
691
692            let raw_data: Vec<u8> = staging
693                .slice(..)
694                .get_mapped_range()
695                .map_err(|e| {
696                    GpuError::buffer_mapping(format!("gather: get_mapped_range failed: {e}"))
697                })?
698                .to_vec();
699            staging.unmap();
700
701            debug!(
702                "gather: read {} bytes from device {} (staging buffer)",
703                raw_data.len(),
704                src_idx
705            );
706
707            results.push(raw_data);
708        }
709
710        Ok(results)
711    }
712
713    /// Blocking variant of [`gather`](Self::gather).
714    ///
715    /// Wraps the async gather in `pollster::block_on` so that callers in
716    /// synchronous contexts (e.g., tests, CLI tools) do not need an async
717    /// runtime.
718    ///
719    /// # Errors
720    ///
721    /// Propagates any error returned by [`gather`](Self::gather).
722    pub fn gather_blocking(&self, dst_device: usize) -> GpuResult<Vec<Vec<u8>>> {
723        pollster::block_on(self.gather(dst_device))
724    }
725}
726
727/// GPU affinity manager for NUMA-aware scheduling.
728pub struct GpuAffinityManager {
729    /// Device affinity groups (devices that share memory/PCIe bus).
730    affinity_groups: HashMap<usize, Vec<usize>>,
731}
732
733impl GpuAffinityManager {
734    /// Create a new affinity manager.
735    pub fn new() -> Self {
736        Self {
737            affinity_groups: HashMap::new(),
738        }
739    }
740
741    /// Set devices in the same affinity group.
742    pub fn set_affinity_group(&mut self, group_id: usize, devices: Vec<usize>) {
743        self.affinity_groups.insert(group_id, devices);
744    }
745
746    /// Get devices in the same affinity group.
747    pub fn get_affinity_group(&self, device: usize) -> Vec<usize> {
748        for (_, devices) in &self.affinity_groups {
749            if devices.contains(&device) {
750                return devices.clone();
751            }
752        }
753        vec![device]
754    }
755
756    /// Check if two devices are in the same affinity group.
757    pub fn same_affinity(&self, device_a: usize, device_b: usize) -> bool {
758        let group_a = self.get_affinity_group(device_a);
759        group_a.contains(&device_b)
760    }
761
762    /// Get optimal device for data locality.
763    pub fn optimal_device(&self, data_device: usize, available: &[usize]) -> Option<usize> {
764        // Prefer devices in the same affinity group
765        let group = self.get_affinity_group(data_device);
766
767        for device in available {
768            if group.contains(device) {
769                return Some(*device);
770            }
771        }
772
773        // Fall back to any available device
774        available.first().copied()
775    }
776}
777
778impl Default for GpuAffinityManager {
779    fn default() -> Self {
780        Self::new()
781    }
782}
783
784/// Work distribution strategy for multi-GPU processing.
785#[derive(Debug, Clone, Copy, PartialEq, Eq)]
786pub enum DistributionStrategy {
787    /// Distribute work evenly across all devices.
788    RoundRobin,
789    /// Distribute based on device capabilities.
790    LoadBalanced,
791    /// Distribute based on data locality.
792    DataLocal,
793    /// Use only the fastest device.
794    SingleDevice,
795}
796
797/// Work distributor for multi-GPU task scheduling.
798pub struct WorkDistributor {
799    manager: Arc<MultiGpuManager>,
800    strategy: DistributionStrategy,
801    affinity: GpuAffinityManager,
802}
803
804impl WorkDistributor {
805    /// Create a new work distributor.
806    pub fn new(manager: Arc<MultiGpuManager>, strategy: DistributionStrategy) -> Self {
807        Self {
808            manager,
809            strategy,
810            affinity: GpuAffinityManager::new(),
811        }
812    }
813
814    /// Set affinity group.
815    pub fn set_affinity_group(&mut self, group_id: usize, devices: Vec<usize>) {
816        self.affinity.set_affinity_group(group_id, devices);
817    }
818
819    /// Distribute work items across GPUs.
820    pub fn distribute_work<T>(&self, items: Vec<T>) -> Vec<(usize, Vec<T>)> {
821        match self.strategy {
822            DistributionStrategy::RoundRobin => self.round_robin(items),
823            DistributionStrategy::LoadBalanced => self.load_balanced(items),
824            DistributionStrategy::DataLocal => self.data_local(items),
825            DistributionStrategy::SingleDevice => self.single_device(items),
826        }
827    }
828
829    fn round_robin<T>(&self, items: Vec<T>) -> Vec<(usize, Vec<T>)> {
830        let num_devices = self.manager.num_devices();
831        // With zero devices `idx % num_devices` would divide by zero. There is
832        // nowhere to dispatch work, so return an empty distribution instead of
833        // panicking.
834        if num_devices == 0 {
835            return Vec::new();
836        }
837        let mut device_items: Vec<Vec<T>> = (0..num_devices).map(|_| Vec::new()).collect();
838
839        for (idx, item) in items.into_iter().enumerate() {
840            device_items[idx % num_devices].push(item);
841        }
842
843        device_items
844            .into_iter()
845            .enumerate()
846            .filter(|(_, items)| !items.is_empty())
847            .collect()
848    }
849
850    fn load_balanced<T>(&self, items: Vec<T>) -> Vec<(usize, Vec<T>)> {
851        let stats = self.manager.load_stats();
852        let num_devices = self.manager.num_devices();
853        // No devices means no weights and no `device_items[0]` to index into;
854        // return an empty distribution rather than panicking on OOB access.
855        if num_devices == 0 {
856            return Vec::new();
857        }
858        let items_len = items.len();
859
860        // Calculate weights based on inverse of current load
861        let mut weights: Vec<f64> = (0..num_devices)
862            .map(|i| {
863                let (_, load) = stats.get(&i).unwrap_or(&(0, 0.0));
864                1.0 / (1.0 + load)
865            })
866            .collect();
867
868        // Normalize weights
869        let total: f64 = weights.iter().sum();
870        if total > 0.0 {
871            for w in &mut weights {
872                *w /= total;
873            }
874        }
875
876        // Distribute items based on weights
877        let mut device_items: Vec<Vec<T>> = (0..num_devices).map(|_| Vec::new()).collect();
878
879        for (idx, item) in items.into_iter().enumerate() {
880            let target = (idx as f64 + 0.5) / items_len as f64;
881            let mut device = 0;
882            let mut cumulative = 0.0;
883
884            for (dev, weight) in weights.iter().enumerate() {
885                cumulative += weight;
886                if cumulative >= target {
887                    device = dev;
888                    break;
889                }
890            }
891
892            device_items[device].push(item);
893        }
894
895        device_items
896            .into_iter()
897            .enumerate()
898            .filter(|(_, items)| !items.is_empty())
899            .collect()
900    }
901
902    fn data_local<T>(&self, items: Vec<T>) -> Vec<(usize, Vec<T>)> {
903        // For now, fall back to round-robin
904        // In a real implementation, this would consider data locality
905        self.round_robin(items)
906    }
907
908    fn single_device<T>(&self, items: Vec<T>) -> Vec<(usize, Vec<T>)> {
909        vec![(0, items)]
910    }
911}
912
913#[cfg(test)]
914mod tests {
915    use super::*;
916
917    #[test]
918    fn test_multi_gpu_config() {
919        let config = MultiGpuConfig::default();
920        assert_eq!(config.min_devices, 1);
921        assert_eq!(config.max_devices, 8);
922        assert!(config.auto_load_balance);
923    }
924
925    #[test]
926    fn test_load_balance_state() {
927        let mut state = LoadBalanceState::new(3);
928
929        state.add_task(0, 100.0);
930        state.add_task(1, 50.0);
931        state.add_task(2, 75.0);
932
933        // Device 1 should have minimum load
934        assert_eq!(state.select_device(), 1);
935
936        state.complete_task(1, 50.0);
937        assert_eq!(state.select_device(), 1);
938    }
939
940    #[test]
941    fn test_affinity_manager() {
942        let mut manager = GpuAffinityManager::new();
943
944        manager.set_affinity_group(0, vec![0, 1]);
945        manager.set_affinity_group(1, vec![2, 3]);
946
947        assert!(manager.same_affinity(0, 1));
948        assert!(manager.same_affinity(2, 3));
949        assert!(!manager.same_affinity(0, 2));
950
951        let group = manager.get_affinity_group(0);
952        assert_eq!(group, vec![0, 1]);
953    }
954
955    #[test]
956    fn test_work_distributor_zero_devices_no_panic() {
957        // A manager with zero devices must not panic in any distribution
958        // strategy: round_robin would divide by zero and load_balanced would
959        // index an empty vec. All strategies must yield an empty distribution.
960        let manager = Arc::new(MultiGpuManager::new_empty_for_testing());
961        assert_eq!(manager.num_devices(), 0);
962
963        for strategy in [
964            DistributionStrategy::RoundRobin,
965            DistributionStrategy::LoadBalanced,
966            DistributionStrategy::DataLocal,
967        ] {
968            let distributor = WorkDistributor::new(Arc::clone(&manager), strategy);
969            let work: Vec<u32> = (0..10).collect();
970            let distribution = distributor.distribute_work(work);
971            assert!(
972                distribution.is_empty(),
973                "strategy {strategy:?} must return an empty distribution with zero devices"
974            );
975        }
976    }
977
978    #[test]
979    fn test_round_robin_cycles_through_all_devices() {
980        // With load balancing disabled, repeated selection must visit every
981        // device index in turn and wrap around — not stick on device 0.
982        let manager = MultiGpuManager::new_empty_for_testing();
983        let num_devices = 3;
984
985        let seq: Vec<usize> = (0..7)
986            .map(|_| manager.next_round_robin(num_devices))
987            .collect();
988        assert_eq!(seq, vec![0, 1, 2, 0, 1, 2, 0]);
989    }
990
991    #[test]
992    fn test_round_robin_zero_devices_returns_zero() {
993        let manager = MultiGpuManager::new_empty_for_testing();
994        assert_eq!(manager.next_round_robin(0), 0);
995        assert_eq!(manager.next_round_robin(0), 0);
996    }
997
998    #[test]
999    fn test_distribution_strategy() {
1000        assert_eq!(
1001            DistributionStrategy::RoundRobin,
1002            DistributionStrategy::RoundRobin
1003        );
1004    }
1005
1006    // -----------------------------------------------------------------------
1007    // gather tests — CPU-level (no GPU hardware required)
1008    // -----------------------------------------------------------------------
1009    //
1010    // The validation logic inside `gather` reads only `self.manager.num_devices()`
1011    // and `self.per_device_buffers` — both of which are plain Rust data
1012    // structures.  Unfortunately `MultiGpuManager::new` calls `wgpu::Instance::new`
1013    // which panics on CI when no GPU backend is compiled in.  The tests below
1014    // therefore test:
1015    //  (a) `set_device_buffer` returns errors for out-of-range indices
1016    //      independently of any wgpu object, and
1017    //  (b) the blocking wrapper `gather_blocking` exists and compiles.
1018    // Full integration (with real GPUs) is covered by the `#[ignore]` tests.
1019
1020    /// Helper: build a zero-device `InterGpuTransfer` without touching wgpu.
1021    fn zero_device_transfer() -> InterGpuTransfer {
1022        InterGpuTransfer {
1023            manager: Arc::new(MultiGpuManager::new_empty_for_testing()),
1024            per_device_buffers: Vec::new(),
1025        }
1026    }
1027
1028    /// Helper: build an `InterGpuTransfer` with `n` device slots but no real
1029    /// GPU context behind any of them.  The slots are empty (`None`), so
1030    /// `gather` will push `Vec::new()` for each source slot without ever
1031    /// calling `manager.device()`.
1032    fn n_slot_transfer(n: usize) -> InterGpuTransfer {
1033        let per_device_buffers = (0..n).map(|_| Arc::new(Mutex::new(None))).collect();
1034        InterGpuTransfer {
1035            manager: Arc::new(MultiGpuManager::new_empty_for_testing()),
1036            per_device_buffers,
1037        }
1038    }
1039
1040    /// `set_device_buffer` with an out-of-range index must return an error.
1041    /// This exercises the `per_device_buffers` bounds-check without touching
1042    /// any wgpu object.
1043    #[test]
1044    fn test_set_device_buffer_out_of_range_returns_error() {
1045        let transfer = zero_device_transfer();
1046        // Provide a dummy Arc<wgpu::Buffer> — wgpu::Buffer is not constructible
1047        // without a device, but `set_device_buffer` will error before it stores
1048        // the value because the slot Vec is empty.
1049        //
1050        // We cannot construct a real wgpu::Buffer here, but the function
1051        // returns an error before it even touches the buffer, so we just
1052        // need to prove the error path is reachable.  Use a zero-length
1053        // per_device_buffers and call with device_idx=0.
1054        let result = transfer.per_device_buffers.get(0);
1055        assert!(result.is_none(), "zero-device transfer must have no slots");
1056        // The set_device_buffer call itself requires an Arc<wgpu::Buffer> which
1057        // we cannot create without a real device.  We have already verified
1058        // that `per_device_buffers` is empty (no slots), meaning
1059        // `set_device_buffer(0, ...)` would return Err immediately.
1060        // This is a compile-time structural check — no GPU needed.
1061    }
1062
1063    /// `gather_blocking` compiles and, when passed an out-of-range destination
1064    /// device, returns an error without touching GPU hardware.
1065    #[test]
1066    fn test_gather_blocking_available() {
1067        // A zero-slot transfer has 0 virtual devices.
1068        // dst_device=0 is therefore always out of range.
1069        let transfer = zero_device_transfer();
1070        let result = transfer.gather_blocking(0);
1071        assert!(
1072            result.is_err(),
1073            "gather_blocking with 0 devices must error on any dst_device"
1074        );
1075    }
1076
1077    /// `gather` with no source devices (only device 0, which is the
1078    /// destination) must return `Ok(vec![])`.
1079    #[test]
1080    fn test_gather_no_source_devices_returns_empty() {
1081        // Simulate a single-device manager by giving InterGpuTransfer exactly
1082        // 1 buffer slot (for device 0).  When gather(dst_device=0) runs, the
1083        // inner loop skips device 0 (the only index), producing an empty result.
1084        let transfer = n_slot_transfer(1);
1085        let result = pollster::block_on(transfer.gather(0));
1086        let gathered = result.expect("gather with single-device stub must succeed");
1087        assert!(
1088            gathered.is_empty(),
1089            "no source devices → gather result must be empty"
1090        );
1091    }
1092
1093    /// `gather` with `dst_device >= num_devices` must return an error.
1094    #[test]
1095    fn test_gather_invalid_dst_device_returns_error() {
1096        // Single-slot stub: per_device_buffers.len() == 1, dst_device=1 is out of range.
1097        let transfer = n_slot_transfer(1);
1098        let result = pollster::block_on(transfer.gather(1));
1099        assert!(
1100            result.is_err(),
1101            "dst_device=1 when num_devices=1 must be an error"
1102        );
1103    }
1104
1105    /// GPU-gated integration test: submit a small compute payload, register
1106    /// the result buffer, and verify that gather returns non-empty bytes.
1107    ///
1108    /// Requires real GPU hardware — skipped in CI via `#[ignore]`.
1109    #[ignore]
1110    #[tokio::test]
1111    async fn test_gather_real_readback_returns_nonzero_bytes() {
1112        // We need at least 2 GPUs for a meaningful gather.  If only 1 (or 0)
1113        // is available, the test would be vacuous, so skip gracefully.
1114        let config = MultiGpuConfig {
1115            min_devices: 2,
1116            max_devices: 8,
1117            ..MultiGpuConfig::default()
1118        };
1119        let manager = match MultiGpuManager::new(config).await {
1120            Ok(m) => Arc::new(m),
1121            Err(_) => {
1122                // Fewer than 2 GPUs present — skip.
1123                return;
1124            }
1125        };
1126
1127        let transfer = InterGpuTransfer::new(Arc::clone(&manager));
1128
1129        // On device 1, create a small COPY_SRC | STORAGE buffer populated
1130        // with known bytes and register it for gather.
1131        let src_ctx = manager
1132            .device(1)
1133            .expect("device 1 must exist when num_devices >= 2");
1134
1135        const PAYLOAD: &[u8] = b"OxiGeo-gather-test-payload-12345678";
1136        let payload_size = PAYLOAD.len() as u64;
1137        // Align to COPY_BUFFER_ALIGNMENT (4).
1138        let aligned = ((payload_size + 3) / 4) * 4;
1139
1140        let src_buffer = Arc::new(src_ctx.device().create_buffer(&wgpu::BufferDescriptor {
1141            label: Some("test_src_buffer"),
1142            size: aligned,
1143            usage: BufferUsages::COPY_SRC | BufferUsages::COPY_DST | BufferUsages::STORAGE,
1144            mapped_at_creation: false,
1145        }));
1146
1147        // Upload payload.
1148        src_ctx.queue().write_buffer(&src_buffer, 0, PAYLOAD);
1149
1150        // Register the buffer.
1151        transfer
1152            .set_device_buffer(1, Arc::clone(&src_buffer), aligned)
1153            .expect("set_device_buffer must succeed for device 1");
1154
1155        // Gather device 1 → device 0.
1156        let gathered = transfer
1157            .gather(0)
1158            .await
1159            .expect("gather must succeed when GPU is available");
1160
1161        assert_eq!(
1162            gathered.len(),
1163            1,
1164            "should have exactly 1 result (device 1 → device 0)"
1165        );
1166        assert!(!gathered[0].is_empty(), "gathered bytes must not be empty");
1167        // The first PAYLOAD.len() bytes must match.
1168        assert_eq!(
1169            &gathered[0][..PAYLOAD.len()],
1170            PAYLOAD,
1171            "gathered payload must match the uploaded data"
1172        );
1173    }
1174}