Struct GpuContext 

pub struct GpuContext {
    pub tuner: WorkgroupTuner,
    /* private fields */
}

GPU context holding device and queue.

This is the main entry point for GPU operations. It manages the WGPU device and queue, and provides methods for creating buffers, pipelines, and executing compute shaders.

Fields

tuner: WorkgroupTuner

Workgroup sizes tuned to this adapter’s limits.

Implementations

impl GpuContext

pub async fn new() -> GpuResult<Self>

Create a new GPU context with default configuration.

Errors

Returns an error if no suitable GPU adapter is found or device request fails.

pub async fn with_config(config: GpuContextConfig) -> GpuResult<Self>

Create a new GPU context with custom configuration.

Errors

Returns an error if no suitable GPU adapter is found or device request fails.

pub fn device(&self) -> &Device

Get the WGPU device.

pub fn queue(&self) -> &Queue

Get the WGPU queue.

pub fn adapter(&self) -> &Adapter

Get the WGPU adapter.

pub fn instance(&self) -> &Instance

Get the WGPU instance.

pub fn adapter_info(&self) -> &AdapterInfo

Get adapter information.

pub fn limits(&self) -> &Limits

Get device limits.

pub fn backend(&self) -> Backend

Get the backend being used.

pub fn supports_feature(&self, feature: Features) -> bool

Check if the device supports a specific feature.

pub fn max_workgroup_size(&self) -> (u32, u32, u32)

Get maximum workgroup size for compute shaders.

pub fn poll(&self, _wait: bool)

Poll the device for completed operations.

This should be called periodically to process GPU operations.

pub fn spawn_poll_task(&self) -> JoinHandle<()>

Spawn a background thread that keeps the wgpu device polled.

This is an advanced helper intended for callers that run async GPU readbacks without a runtime that issues device polls automatically (e.g. bare pollster or custom executors).

The spawned thread calls device.poll(wgpu::PollType::Poll) in a tight loop with a 1 ms sleep between iterations. Call std::thread::JoinHandle::join when the thread is no longer needed (the caller is responsible for signalling termination through a shared flag or by dropping all Arc<Device> clones and letting the thread detect the closed handle).

In most tokio/async-std environments the runtime’s built-in submission loop makes this unnecessary.

pub fn is_valid(&self) -> bool

Check if the device is still valid.

pub fn with_tuner(self, tuner: WorkgroupTuner) -> Self

Override the workgroup tuner (useful in tests or for custom tuning).

Returns self so it can be chained in a builder-style pattern:

let gpu = GpuContext::new().await?.with_tuner(WorkgroupTuner::unlimited());

pub fn is_device_lost(&self) -> bool

Returns true if the GPU device has been lost and operations will fail.

The flag is set atomically by the wgpu device-lost callback registered during GpuContext::new / GpuContext::with_config.

pub fn check_device_lost(&self) -> GpuResult<()>

Checks whether the device has been lost and returns an error if so.

Call this before every queue.submit to short-circuit operations on a defunct device instead of generating silent GPU errors.

pub fn pipeline_cache(&self) -> &SharedPipelineCache

Returns a reference to the shared pipeline cache.

The cache maps (shader_hash, entry_point, layout_tag) keys to previously compiled wgpu::ComputePipelines wrapped in Arc.

Kernel implementations can call PipelineCache::get_or_insert_with on the inner crate::pipeline_cache::PipelineCache to avoid recompiling the same WGSL shader on every kernel construction.

Examples

use oxigdal_gpu::{GpuContext, pipeline_cache::PipelineCacheKey};

let cache = ctx.pipeline_cache();
if let Ok(mut guard) = cache.lock() {
    println!("cached pipelines: {}", guard.len());
}

pub fn with_device_lost_flag(self, flag: Arc<AtomicBool>) -> Self

Replaces the internal device-lost flag with an externally-supplied one.

This builder method is intended for testing only — it allows a test to inject a shared Arc<AtomicBool> whose state it controls directly, exercising the check_device_lost / is_device_lost paths without requiring a real GPU device.

use std::sync::{Arc, atomic::{AtomicBool, Ordering}};
// NB: GpuContext::new() requires a GPU; this is conceptual.
// let ctx = ctx.with_device_lost_flag(Arc::new(AtomicBool::new(true)));

pub async fn reinitialize(&self) -> GpuResult<GpuContext>

Attempts to recreate the GPU device on the same adapter.

This creates a fresh GpuContext via the same wgpu instance, selecting an adapter with matching properties to the one this context was built on. The old context must be dropped after calling this method; continuing to use it will only generate further device-lost errors.

Errors

Returns an error if adapter enumeration fails or the device cannot be re-created (e.g., the GPU has been physically removed).

Trait Implementations

impl Clone for GpuContext

fn clone(&self) -> GpuContext

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for GpuContext

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.