Class MetalExecutionEngine

Namespace

DotCompute.Backends.Metal.Execution

Assembly

DotCompute.Backends.Metal.dll

Orchestrates Metal kernel execution with explicit grid and thread group dimensions. Manages command buffer lifecycle, encoder setup, and synchronization.

public sealed class MetalExecutionEngine : IDisposable

Inheritance

object

MetalExecutionEngine

Implements

IDisposable

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Extension Methods

BufferExtensions.IsSafeToDispose(IDisposable)

BufferExtensions.SafeDispose(IDisposable)

Constructors

MetalExecutionEngine(nint, nint, ILogger<MetalExecutionEngine>?)

Initializes a new instance of the MetalExecutionEngine class.

public MetalExecutionEngine(nint device, nint commandQueue, ILogger<MetalExecutionEngine>? logger = null)

Parameters

device nint

The Metal device handle.

commandQueue nint

The Metal command queue handle.

logger ILogger<MetalExecutionEngine>

Optional logger for diagnostic information.

Methods

Dispose()

Disposes the execution engine and releases native resources.

public void Dispose()

Execute(MetalCompiledKernel, GridDimensions, GridDimensions, params IUnifiedMemoryBuffer[])

Executes a compiled Metal kernel with explicit grid and thread group dimensions (synchronous version).

public void Execute(MetalCompiledKernel kernel, GridDimensions gridDim, GridDimensions blockDim, params IUnifiedMemoryBuffer[] buffers)

Parameters

kernel MetalCompiledKernel

The compiled Metal kernel to execute.

gridDim GridDimensions

The grid dimensions (number of thread groups to dispatch).

blockDim GridDimensions

The thread group dimensions (threads per thread group).

buffers IUnifiedMemoryBuffer[]

Buffer parameters to bind to the kernel.

Remarks

This is a synchronous convenience method that blocks until kernel execution completes. For better performance in async contexts, use ExecuteAsync(MetalCompiledKernel, GridDimensions, GridDimensions, IUnifiedMemoryBuffer[], CancellationToken) instead.

Exceptions

ArgumentNullException

Thrown when kernel or buffers is null.

ArgumentException

Thrown when grid or block dimensions are invalid.

ObjectDisposedException

Thrown when the engine has been disposed.

InvalidOperationException

Thrown when Metal operations fail.

ExecuteAsync(MetalCompiledKernel, GridDimensions, GridDimensions, IUnifiedMemoryBuffer[], CancellationToken)

Executes a compiled Metal kernel with explicit grid and thread group dimensions.

public Task ExecuteAsync(MetalCompiledKernel kernel, GridDimensions gridDim, GridDimensions blockDim, IUnifiedMemoryBuffer[] buffers, CancellationToken cancellationToken = default)

Parameters

kernel MetalCompiledKernel

The compiled Metal kernel to execute.

gridDim GridDimensions

The grid dimensions (number of thread groups to dispatch).

blockDim GridDimensions

The thread group dimensions (threads per thread group).

buffers IUnifiedMemoryBuffer[]

Buffer parameters to bind to the kernel.

cancellationToken CancellationToken

Optional cancellation token.

Returns

Task

A task representing the asynchronous execution operation.

Remarks

Grid dimensions specify how many thread groups to launch. For example, gridDim=(10, 1, 1) launches 10 thread groups in the X dimension.

Block dimensions specify threads per thread group. For example, blockDim=(256, 1, 1) creates thread groups with 256 threads each.

Total threads = gridDim × blockDim. For the example above: 10 × 256 = 2,560 threads.

Exceptions

ArgumentNullException

Thrown when kernel or buffers is null.

ArgumentException

Thrown when grid or block dimensions are invalid.

ObjectDisposedException

Thrown when the engine has been disposed.

InvalidOperationException

Thrown when Metal operations fail.