Class NamedAcceleratorWrapper

Namespace

DotCompute.Plugins.Core

Assembly

DotCompute.Plugins.dll

Common wrapper to provide named accelerator support across all backends. This consolidates the duplicate NamedAcceleratorWrapper implementations.

public sealed class NamedAcceleratorWrapper : IAccelerator, IAsyncDisposable

Inheritance

object

NamedAcceleratorWrapper

Implements

IAccelerator

IAsyncDisposable

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

Initializes a new instance of the NamedAcceleratorWrapper class.

Constructors

NamedAcceleratorWrapper(string, IAccelerator)

Common wrapper to provide named accelerator support across all backends. This consolidates the duplicate NamedAcceleratorWrapper implementations.

public NamedAcceleratorWrapper(string name, IAccelerator accelerator)

Parameters

name string

The name for this accelerator.

accelerator IAccelerator

The underlying accelerator instance.

Remarks

Initializes a new instance of the NamedAcceleratorWrapper class.

Exceptions

ArgumentNullException

Thrown when name or accelerator is null.

Properties

Context

Gets the accelerator context.

public AcceleratorContext Context { get; }

Property Value

AcceleratorContext

Exceptions

ArgumentNullException

Thrown when name or accelerator is null.

DeviceType

Gets the device type as a string (e.g., "CPU", "GPU", "TPU").

public string DeviceType { get; }

Property Value

string

Exceptions

ArgumentNullException

Thrown when name or accelerator is null.

Info

Gets device information.

public AcceleratorInfo Info { get; }

Property Value

AcceleratorInfo

Exceptions

ArgumentNullException

Thrown when name or accelerator is null.

IsAvailable

Gets whether the accelerator is available for use.

public bool IsAvailable { get; }

Property Value

bool

Exceptions

ArgumentNullException

Thrown when name or accelerator is null.

Memory

Gets memory manager for this accelerator.

public IUnifiedMemoryManager Memory { get; }

Property Value

IUnifiedMemoryManager

Exceptions

ArgumentNullException

Thrown when name or accelerator is null.

MemoryManager

Gets the memory manager for this accelerator (alias for Memory).

public IUnifiedMemoryManager MemoryManager { get; }

Property Value

IUnifiedMemoryManager

Exceptions

ArgumentNullException

Thrown when name or accelerator is null.

Name

public string Name { get; }

Property Value

string

Exceptions

ArgumentNullException

Thrown when name or accelerator is null.

Type

Gets the accelerator type.

public AcceleratorType Type { get; }

Property Value

AcceleratorType

Exceptions

ArgumentNullException

Thrown when name or accelerator is null.

Methods

CompileKernelAsync(KernelDefinition, CompilationOptions?, CancellationToken)

Compiles a kernel for execution.

public ValueTask<ICompiledKernel> CompileKernelAsync(KernelDefinition definition, CompilationOptions? options = null, CancellationToken cancellationToken = default)

Parameters

definition KernelDefinition

options CompilationOptions

cancellationToken CancellationToken

Returns

ValueTask<ICompiledKernel>

Exceptions

ArgumentNullException

Thrown when name or accelerator is null.

DisposeAsync()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources asynchronously.

public ValueTask DisposeAsync()

Returns

ValueTask

A task that represents the asynchronous dispose operation.

Exceptions

ArgumentNullException

Thrown when name or accelerator is null.

GetHealthSnapshotAsync(CancellationToken)

Gets a comprehensive health snapshot of the device including sensor readings, health status, and performance metrics.

public ValueTask<DeviceHealthSnapshot> GetHealthSnapshotAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

Cancellation token.

Returns

ValueTask<DeviceHealthSnapshot>

A task containing the device health snapshot.

Remarks

This method queries the device for real-time health information including: - Temperature, power consumption, and utilization - Memory usage and availability - Error counts and device status - Throttling information

Performance: Typically takes 1-10ms to collect all metrics. For high-frequency monitoring, consider caching snapshots for 100-500ms.

Orleans Integration: Use for grain placement decisions and health monitoring.

Exceptions

ArgumentNullException

Thrown when name or accelerator is null.

GetProfilingMetricsAsync(CancellationToken)

Gets current profiling metrics from the device.

public ValueTask<IReadOnlyList<ProfilingMetric>> GetProfilingMetricsAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

Cancellation token.

Returns

ValueTask<IReadOnlyList<ProfilingMetric>>

A task containing the collection of profiling metrics.

Remarks

This is a lighter-weight alternative to GetProfilingSnapshotAsync(CancellationToken) when you only need raw metrics without statistics or recommendations.

Exceptions

ArgumentNullException

Thrown when name or accelerator is null.

GetProfilingSnapshotAsync(CancellationToken)

Gets a comprehensive profiling snapshot of accelerator performance.

public ValueTask<ProfilingSnapshot> GetProfilingSnapshotAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

Cancellation token.

Returns

ValueTask<ProfilingSnapshot>

A task containing the profiling snapshot.

Remarks

This method provides detailed performance metrics including: - Kernel execution statistics (average, min, max, percentiles) - Memory operation statistics (bandwidth, transfer times) - Device utilization metrics - Performance trends and bottlenecks - Optimization recommendations

Performance: Typically takes 1-5ms to collect all metrics. Profiling overhead is minimal (<1%) when not actively querying.

Use Cases: Performance optimization, backend selection, monitoring dashboards.

Exceptions

ArgumentNullException

Thrown when name or accelerator is null.

GetSensorReadingsAsync(CancellationToken)

Gets current sensor readings from the device.

public ValueTask<IReadOnlyList<SensorReading>> GetSensorReadingsAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

Cancellation token.

Returns

ValueTask<IReadOnlyList<SensorReading>>

A task containing the collection of available sensor readings.

Remarks

This is a lighter-weight alternative to GetHealthSnapshotAsync(CancellationToken) when you only need raw sensor data without health scoring or status analysis.

Exceptions

ArgumentNullException

Thrown when name or accelerator is null.

ResetAsync(ResetOptions?, CancellationToken)

Resets the accelerator device to a clean state.

public ValueTask<ResetResult> ResetAsync(ResetOptions? options = null, CancellationToken cancellationToken = default)

Parameters

options ResetOptions

Reset configuration options. If null, uses Default.

cancellationToken CancellationToken

Cancellation token.

Returns

ValueTask<ResetResult>

A task containing detailed information about the reset operation.

Remarks

Device reset clears device state and optionally reinitializes resources. The extent of reset depends on ResetType:

• Soft: Flush queues, clear pending operations (1-10ms)
• Context: Reset context, clear caches (10-50ms)
• Hard: Full reset, clear all memory (50-200ms)
• Full: Complete reinitialization (200-1000ms)

Important: Hard and Full invalidate all existing UnifiedBuffer instances. The application must recreate buffers after reset completes.

Orleans Integration: Use during grain deactivation, error recovery, or when transferring device ownership between grains. Consider GrainDeactivation for typical grain lifecycle scenarios.

Error Recovery: When recovering from device errors or hangs, use ErrorRecovery which forces a hard reset and clears all state.

Thread Safety: Reset operations are thread-safe. Concurrent operations will wait for completion or be cancelled depending on WaitForCompletion.

Exceptions

TimeoutException

Thrown if reset exceeds Timeout.

InvalidOperationException

Thrown if reset cannot be performed (e.g., device lost).

ObjectDisposedException

Thrown if the accelerator has been disposed.

SynchronizeAsync(CancellationToken)

Synchronizes all pending operations.

public ValueTask SynchronizeAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

Returns

ValueTask

Exceptions

ArgumentNullException

Thrown when name or accelerator is null.